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This. edition of the manual applies to B version 4, 
‘The section on machine-level linkage conventions in | 
chapter 6 has been totally rewritten to reflect the change 
In the run time stack format. 


Parts of Chapter 7 have been changed to reflect the new 
conventions for accessing files with OPEN, 
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1. Introduction. 


This manual describes the programming language 8 ac- 
cepted by the compiler written at the University of Waterloo 
by R. Braga. It also introduces the runtime package written 
at the University of Waterloos largely by T.J. Thompson, 

A derivative of BCPLs B was designed and first imple- 
mented by D.M. Ritchie and Keele Thompsons of Bell Telephone 
Laboratoriess Inc.» Murray Hills NeJ.w The original implemen- 
tation of the runtime package is due to S.C. Johnsons also 
of Bell Labs. 

The present version of the compiler differs from the 
original by incorporating an expanded SWITCH statements ad- 
ding floating point operatorss adding proper logical opera- 
torss and altering the order of evaluation of operators, 

The runtime package works in both TSS and batch and 
will read almost any “media code” found in the GCOS environ- 
ment. It uses EIS instructions whenever it 1S appropriate. 
Note that the language itself has no etonstructs fer: 
input/output, all i/o is done by function calls. 


B is a typeless languages in which the compiler always 
assumes the type of a variable is suitable to the gperator 
acting upon it. 8B has a large set of operatorss providing 
integers bitwises logical and floating point operations. 

The machine word is the basic unit of computation. The 
word size on the Honeywell Series 60 Level 66 or Series 6000 
machines is 36 bits. 

A B program consists of procedures called functions. 
Any function may call another function ors since local vari- 
ables are allocated on a stacks, call itself recursively. All 
functions may selectively access a global pool of externals. 

A function iS composed of a set of one or more gtate- 
ments. A statement is composed of permissible combinations 
of keywords and expressions. 

Although this is a reference manuals and definitely not 
a tutorial» it is organized such that you will often find 
examples which involve material covered later on, This 1s 
intentional. Such examples should be ignored at first read- 
ings but will hopefully be beneficial when you refer to the. 
manual again. : 

You should try to keep your first efforts at B program- 
ming as simple as possibles in order to.minimize the diffi-. 
culties you may encounter. If you are ever unsure of some 
feature of the language or run-time packages try it out by 
writing and running a simple little program which exercises 
only that feature. The time you take to do so may Save you a 
lot of trouble in the tong run. 

Before starting on your first major 8B programs you 
would be well advised to have a close look at’ the source 
code of a well-written 8B program or two in order to get some 
idea of exactly how things are done. 
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2. Basic symbols. 


B is very much oriented towards use of the ASCII char- 
acter set in which each character occupies nine bits (four 
characters per word). There 1S support for representing 
character constants in the BCD character sets in which one 
character occupies six bits (six characters per word), 

Certain charactersse such as *{* or '}*, do not appear 
on some terminal keyboards. Escape sequences for these are 
defined in Appendix A. 

The compiler treats its input as an unbroken stream of 
characters. Any form feeds tabs or newline character 1s con- 


verted to the space characters except when it occurs inside 


a string or character constant. Newlines are counteds so the 
compiler can tell you on what Line it detected an error. 
Line length may be arbitrary. The compiler knows nothing a- 
bout any "sequence field”"s such as 18 Supported by certain 
card-oriented compilers. 

Line-numbered source files are permitted. If the first 
character of the first file is a digits the compiler assumes 
the program being compiled has line numbers. If sos on each 
Line of the files, it attempts to form a line number by col- 
lecting numeric characters until a non-numeric character 1s 
found. The number is used in error messages pertaining to 
that tine... 


2.1. Identifiers. | 
An identifier or name is formed from the characters a- 


ze A-~Ze 0-94 underscore ('_*) or dot ('."')s and must begin 


with a non-digit. Since the run time package uses names con- 
taining at least one dots you should avoid conflicts by not | 


using the dot character in names defined in your program. 
Names may be arbitrarily longs but only the first eight 
characters are significant. For external names or external 
referencesSs only the first six characters are significant, 
due to the restriction imposed by the GCOS and TSS loaders. 


Normallys the compiler ignores case distinctionss sO 


that the identifiers "SUM", "sum" and "Sum™ would be con- 
sidered to be the same thing. You may spvecify an option to 
the compile command which forces the compiler to respect 
case distinctionss but then all keywords must appear in 
lower case, 
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2-2. Comments. | : | 

The beginning of a comment is signalled by the appear- 
ance of a"/*x*" in the input stream. It is ended with the 
first occurrence of a "*/" any number of characters or lines 
later. For example, 


/* 
* this 18 a comment 
xf 


Comments may not be nested, 


Q2-3- Keywords. 
B uses 15 keywordsse which may be categorized as fol- 
lows: 
1) tdentifier scope keywords: 
AUTO EXTRN 
2) execution flow control keywords: | 
IF ELSE FOR WHILE REPEAT SWITCH DO 
3) transfer keywords: 
RETURN BREAK GOTO NEXT 
4) switch statement keywords: 
CASE DEFAULT 3 


The compiler does not allow you to use any keyword = as an 
identifier. In particulars beware of inadvertently using 
NEXT as an identifier, 


2-4. Constants. : | 
You may define octalse decimals floating points ASCII 


characters BCD characters or string constants in your pro- 


nent cnet am 


gram. The form of a constant is well=-defineds in that it is 
possible to unambiguously differentiate between the various 
types of constants. 


2-4-1. Decimal constants. 


A decimal constant consists of an integer numbers which may 
not contain leading zeroes. For example: 


e5 4737 961 xe 
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2.4.2. QOstal constants. 


An octal constant consists of an integer numbers preceded by 
a zero and formed only from the digits zero through seven. 
For examples 


01 O77? 026 0400000 O777777 777777 


2.4.3. Floating point decimal constants. 


A floating-point constant is any number containing a decimal 
point. It must not begin with a decimal points but may have 
leading zeroes and may be followed by the letter ‘e'" and a 
possibly siqned integer exponent. Examples: 


Sue 2 055 TeeS Seeds 4.987 e-2 


2-4-4. ASCII character constants. 


An ASCII character constant consists of from one_ to four 
characters inside single quotes. The result is a word which 
contains the internal form of the ASCII characterss right- 
adjusted and left-padded with zero bits. Some examples; 


a. Be ‘abc * "abcd! 


The compiler counts characters inside character constants 
and issues an error message if there are more than four. 


2-4.5- BCD character constants. 


A BCD constant consists of from one to six characters en- 
closed by grave accent characters. The result is a word con- 
taining the characters transliterated to 8CD- right justi- 
fieds and tleft-padded with zero bits. Characters which do 
not have an exact equivalent in the BCD set are converted to 
BCD blanks. Here are three examples of BCD constants: 


a Ot "123456° 


If your terminal does not have a grave accent character you 
may alternately alternately write a BCD constant like an AS- 
CII character constants except preceded by a dollar signs as 
mn 
Sta Stott 377423456" 

3 Note that the runtime package provides functions to 
transliterate between ASCII and BCD and that the i/o funcn- 
tion PRINTF will take a BCD format specification. 
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204.6. StFINg Coostants. 


A string constant is any string of characters enclosed in 
double quotes. For examples: 


"this 48. 4 string 


"the above is the null string” 


When processing a strings the compiler packs the characters 
of the string four per word and always appends one extra 
characters jan ASCII nult €000), to mark the end of the 
string. : 


The value of a string is quite different from the other 
types of constants. The value of a floating-points octal, 
decimal or character constant is aword containing the 
internal representation of the given constant. The value of 
a string constant is a word containing the address of the 


In constructing the strings the compiler gobbles all 
characters it seess translating escape sequences if neces- 
sarye until it finds a closings unescaped double quote. The 
rule which says tabs and form feeds are ignored does nots of 
courses apply in this cases but real newlines (as opposed to 
escaped newlines) are treated specially. If a real newline 
is preceded by a ‘*',s both ‘'** and newline are thrown away, 
sO you can enter a very long line. If the newline is not 
preceded by a '*", it is kept» but a warning message 1S 1S 
sueds on the grounds that you probably forgot the closing 
string quote. To get a newline in a string without drawing a 
warnings use the escape ‘n°, 


CwSele ESGabe Seauences. 


Escape sequencesese beginning with the character ‘**', are de- 
fined to allow you to uses in a string or character con- 
stants characters which would otherwise be inconvenient or 


impossible to enter. For examples if you wanted to place a 


double quote inside a string constants you would use the es- 
cape '*"*,. The special end-of-string character (ASCII null) 
1s escaped as "*O". The newline character 1s eScaped as 
‘xn'. A newline is taken aS a carriage return and a line 
feed when output to a terminal. Arbitrary nine-bit charac~ 
ters can be generated with ‘*#nnn's where nnn 1s One to 
three octal digits. The complete set of escape sequences is 
given in Appendix A, 
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2-2. Source file inclusion. 
If the compiler encounters in the source program a 
Line of the form 


4Zfilename 


it suspends processing of the current file and begins col- 
lLecting input from the specified file. When end-of-file is 
encountered in the included files processing in the original 
file resumes at the next line following the file inclusion 
request. Such included files may themselves contain 
"“%filename” requests pointing to other files. : 

The ‘%Z' character mnust be the first character on the 
Lines not just the first non-blank character. If the line 
has a line numbers the '%' must immediately follow the line 
number, | 

The file name given may be in any of the forms accept- 
able in the TSS environments such as 


Zatempo 

AZAfmain.b 
Afbaggins/dif.b 
%Zfbaggins/s/dif.b 
O10%fbaggins/s/dif.b 


This allows you to keep parts of a large module broken 
up into easily manageable filess while retaining the ability 
to compile the files together. File inclusion is also often 
used to bring in a file of manifest definitionss such as TS$S§ 
Derail equivalencess which a variety of possibly unrelated 
programs might find useful. 


2-6- Compiler directives. 

Any Line whose first character is a ‘#* is assumed to 
be one of the compiler directives shown below. In each cases 
"<text>” denotes astring of characters which begins with 
any non~blank character. 


H#title <text> 


wilt place “"“<text>" in the comments field of any & OBJECT 
card written from the time the directive is encountered. 


#lbL <text> 


will place "<text>", truncated to eight characters if neces- 
sarye in the "deck name" field of any $ OBJECT or & DKEND 
card written from the time the directive is encountered. If 
this directive has not been encountered when it comes time 
to generate an object decks then the current file name 15 
used instead. 
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Attldat <text> 


After being truncated to six characters if necessarys 
"<text>" is used to fittl. imethe . “ttt” date. field of. @eny:s 
OBJECT card written from the time the directive is encoun- 
tered, 


#copyright <text> 


1s taken as comments. _ 
Here is an example of the use of all four directives: 


#title tss login subsystem ~- .tslog 

A#lbl tlga 

Httldat 771209 

#oopyright (c) by the University of Waterloos 1977, 


3. Ihe building blocks of a B program. 


A complete B program consists of at least ones but 
usually manys modules. A module is any of the following: 


1) a manifest constant identifier definition. 
2) an external (global) variable definition. 
3) a function body definition. 


Modules may appear in any order at alls» with the sole pro- 
viso that the definition of a manifest identifier must ap- 
pear before the identifier is first used. 

Manifest definitions are used to associate a name with 
a compile time constant. 

External definitions are used to create a global pool 
of possibly initialized identifiers. This pool might be used 
to declare large blocks of memorys or to declare identifiers 
that must be accessible to more than one 8B function. Since 
an external is global in scopes any 8 function may use its 
but only after declaring its intention to do so in an EXTRN 
statement. 

A function definition is used to declare a component of 
the executable code of the orogram. The definition includes 
the name the function will be called bys the arguments it 
will be called withsr and the statements which define what it 
will reference and what it will do. 
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Sel. Manifest constants. 
A manifest constant has the general form 


name = text, 


where "name" is any valid tdentifier and “text” is the colt= 
lection of characters between the equals sign and the semi- 
colon. ; : 

When a manifest is definedse the compiler enters” the 
identifier in the symbol table and associates it with the 
"text", which it keeps in an internal buffer. Absolutely no 
processing of the "text" is done at the time of definition, 

When the compiler reads an identifiers it first checks 
to see if the identifier is a manifest. If sos the action 
taken is to substitute the text of the manifest for. the 
identifier. For this reasons it 1s not possible to speak of 
redefining a manifest and any inadvertent attempt to do so 
will usually result ina syntax error. Substitution effec- 
tively takes place before the syntax analyzer scans’ the 
Line. Manifests may be used anywheres including inside later 
manifest definitions. 

Because the compiler does not analyze the. text of the 
manifest until substitution takes places it is possible for 
the text to refer to a manifest which is defined after its 
as long as the definitions of both appear before the first 
uS@. . 
The use of manifests has no effect on the order of ex- 
pression evaluation. For examples look at the definitions _ 


A = 13 
B = AtA,; 
C = B*B, 


When "C" is used somewhere else in the programs the compiler 
will. actually get “Tt1#141"%>, which witti be evaluated as 
three and not fours as one might mistakenly assume, 
The compiler permits nesting up to 10 levels. deep of 
manifests inside other manifests. : 
Normally» howevers you will find manifests quite natur- 
al to use. Here are some examples of manifests: 3 


VECSIZE = 63, 
vec € VECSIZE 23 


for( i = Of i <= VECSIZEs ++1 ) sum += veclil]; 
The manifest "vecsize” is used to establish the size of the 


vector "vec” at compile times and later used to control 
iteration in a FOR statement. 
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/* binary list structure */ 
NULL =. -7 EMPTY = O- 
CONTENTS , 
LEFT_PTR : 
RIGHT_PTR = 2; 
printree( ptr ) 

if{ ptr != NULED 

{ 


tl i) Se 


0 
- 


printree( LEFT_PTREptr] )-- 
print_contents( CONTENTSECptr] )-. 
printree(RIGHT_PTREptr] ): 
} 
/x end printree */ 


Heres, manifests are being used to make the code involved in 
traversing a binary tree more meaningful. Manifests are 
often used in this way to give names to the elements of a 
structures which may be an array of fixed sizes or a dynami-~ 
cally allocated block of storage. 

A common conventions used in this documents is to dif- 
ferentiate manifest identifiers from other identifiers by 
always showing the manifest identifier in upper cases and to 
show all others in lower case. It is also considered good 
practice to group all manifests for a program together at 
the beginning of the source code. 


3.2. External definitions. 


We will first look at the possible forms of external. 


definitionsse then look at several examples. 


If an external is defined and possibly initialized in 


more than one places the first one encountered during load- 
ing 18 the one which is used. 


These are the possible forms of external definitions: 


name-s 
A single word its allocated and initialized to zero. 


name { ival }- 
"Name" is defined as a single word and initialized with 
the single value ival. 

Ivyal may be any tegal constant expressions in 
which case "name" has the value of its result. A constant 
expression may be either a string constant or an expres~ 
sion formulated with any legal combination of numeric or 
character constantss binary operatorss unary operators 
and parenthesess following the rules in the chapter on 
expressions. Alternativelys ival may be a names in which 
case the value of the ival is a word containing the ad- 
dress of the name given. A function name may be used. 
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name { ivals ivals ... }- 
Allocates space for as many words as there are ivals. 
This 18 in effect a vector which does not have a word set 
aside as a pointer to it, its address is "&name", rather 
than just “name"s which in this case refers to the first 
ival. This is the way a vector Is set up in FORTRAN» but 
1s not the same as a 8 vector. 


name [€ const-expr jj, 

This 1s the first of several forms of 8B vector declara- 
tions. “Name” is defined as a pointer to a vector whose 
length 1s anumber of words which is the value. of the 
constant expression. plus one (since all B vectors start 
subscripting at zero). The zeroth element of the vector 
1s initialized to zeros the initial contents of the 
remaining cells are undefined. 

The const-expr in brackets may be any expression 
which 18 a legal combination of numeric or character con- 
stantse unary operators,e binary operatorses and 
parentheses. It 18S up to you to-make sure the value of 
the expression is reasonables since the compiler's gram- 
mar lets it accept things Like floating point constants 
and negative numberss which give absurd results. For all 
practical purposess “consttexpr”™ must be such that it 
gives an integer result. 


name CL] { ivale ivals we. }s 
"Name" is defined as a pointer to a vector whose length. 
is the number of initial values. ee 


name (C const-expr J] { ivals ivalse wee Fe 
"Name" is defined as a pointer to a_ vector whose length 
1s the maximum of the result of the constant expression 
plus one and the number of initial values. The contents 
of those vector elementss which do not have corresponding 
initial valuess are undefined. 


For compatibility with a previous version of the com- 
pilers B also accepts an ival or ival list which 18 not sur- 
rounded by braces. In this cases» the compiler does not per- 
mit a constant expression to appear. Only a numerics char- 
acter or string constant 1s acceptables although a numeric 
constant may be prefixed by an integer unary minus sign. 
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Here are some examples of external definitions: 


a £°40-3- | 
One word of storage 1s allocateds initialized to the de- 
cimal constant 10 and associated with the name "a", 


RoE { *ab’s ‘edets “fent® 33 
One word 1s associated with the name “b" and initialized 
with a pointer to a vector of three words. The first ele- 
ment of the vectors referred to as "bL0IJ", is initialized 
with the character constant ‘ab’. The other two elements, 
"bCITI™" and “bC2)", are initialized with ‘cde’ and ‘fghi', 
respectively. 


t <2 "*>. Sabe’. 33 
"“c™ is defined and associated with a word containing 
‘ab*. The word immediately following 1s initialized to 
the constant ‘abc's but 18 not associated with any name, 
This 18 in effect a vector which does not have a word set 


aside as a pointer to it. 


d{C63); 
Defines "d" and associates it with aword containing a 
pointer to a vector of 64 wordss whose initial contents 
are undefined. 


ef10) { ae be co d Fe 


Declares “e" and associates it with a vector of 11 words. 
Words zeros ones two and three are initialized with the 


addresses of the externals "a"s "bs "c" and "d"» respec 


tively. The contents of the remaining elements are unde 


fined. 


1, © Vecat ring” <2 
This 718 the usual way of defining an external string with 
an initial value. "f" is defined and initialized with a 
pointer to the storage occupied by the string constant "a 
string”. 


gC] {€ “pascal/library"s "pascal/compiler”"s -1 }- 

This sets up avector of strings with an end marker, It 
defines "g" and associates it with a word containing a 
pointer to a vector of three words. The cett “gl03" is 
initialized with a pointer to the storage occupied by the 
string constant “pascal/library”. The cell “gliJ" is ini- 
tialized in a similar manners while "gf2]", the last ele- 
ment of the threer-word vectors 18 initialized to the de- 
cimal constant ~1. : 


B does not allow you to explicitly declare arrays with 
more then one dimension. Usually if you need more than one 
dimensions you build it at run time by calling the library 
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function GETMATRIXs which will obtain storages construct the 
necessary edge vectors and return a pointer to the array. 
Howevers, 1n spite of the fact that you cannot declare such 
an arrays it is possible to construct one as an initialized 
external! The secret is that any ival (Cinside braces) may be 
replaced by an ival or ival list surrounded by braces. The 
compiler then constructs the ival list and places a pointer 
to it in the original ival list. The maximum nesting depth 
1s seven. For example, 


¥E Jt 
{ O00,-07% O2 3s 
{ 105 ls 12. ys 
{ 287 216. 7229 
+; 


In this cases "x" ends up being initialized as a pointer to 


a vector containing three pointers. Each pointer points to a 
vector of three words. In an expressions the value of "xf{0J" 
1S a pointer to the first vector of three wordss while the 
vyatuye- of “xET IC 21% 18— Te. 


3.3. Eunction definition. 

B functions serve a purpose similar to the subroutine 
in FORTRAN or the procedure in ALGOL, The mechanism of the 
function call involves very Little cost in overhead and per- 
mits recursion. 3 sen 2 

A working B program always contains at least one func- 


tions called MAIN» and usually otherss since the language 1s 


designed to encourage modular or structured programming. 
The general form of a function definition is 


name( argisv arg2s eee ) Statement 


The name must be a valid identifier and is automatically de- 
fined as an external by the compiler. 

The formal arguments consist of a possibly empty list 
of identifers separated by commas. Each argument is impli- 
citly declared as an automatic (local) variable and storage 
for it is allocated on the runtime stack frame. Note thats 
although you may not declare a vector as a formal argument, 
you can always use an argument in a subscripting operations 
as if it were a vector pointer. 

*"Statement™” defines what actions the function will 
take. Most oftens it is a compound statements consisting of 
a set of statements enclosed by braces. The rules for formu- 
lating statements are presented in the next chapter. 

When writing the code for a functions there are a few 
things you should keep in mind. 

The caller will always pass its arguments. strictly by 
value. This means that altering an argument has no effect on 
the state of the caller. Howevers if an argument 1s_a 
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pointers you can change the state of the caller by 
indirecting through the pointer using either the unary in- 
direction operator or subscripting. 

The function may at any time return a one word value 
using the RETURN statement. The caller and the callee do not 
have to agree on whether or not a value is returned. If a 
value is returnede but not expecteds the value is ignored. 
If a value is expected, but not returneds, the value 1s unde- 
fined. 

A function can determine the actual number of arguments 
it is called with by invoking the library function NARGS. 
For instances the statement 


x = nargs()-, 


would assign to the variable "x" the number of arguments 
supplied to the current invocation of the function. | 

The availability of NARGS lets you write functions 
which may take a variable number of arguments. Most of the 
timer this means that such a function 1s called with fewer 
arguments than are defined for ite in which case one of the 
first things such a function does is to establish default 
values for the arguments it does not have, 

The other caser in which a function is called with more 
arguments than are defined for its is somewhat trickiers and 
should be avoideds unless you know precisely what you are 
doing. 

The function called MAIN is the entry point to your 
program from the B runtime initialization routine. If not — 
presents the TSS loader prints the message: co 


<w> main undefined 


For details on how your main function 1s invokeds see 
the chapter on the run time library. 
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‘4. Statements. 


Statements are used to define the actions taken by a B 
function. They may apoear only in the body of a function de- 
finition. In certain casesse the definition of a statement is 
recursives in that a statement may appear inside a state- 
ment. In this chapters you will see that in many caseSs one 
may use an expression 1n a statement. Since the rules for 
formulating expressions are discussed in the next chapters 
we merely note here that an expression may be a statement, 
but a statement may not appear in an expression, 

In every case where a statement 1s nermitteds it may be 
replaced by a gompound statements consisting of one or more 
statements enclosed in curly bracess as in 


{ 
statement! 
statement2 
} 


The compiler does not permit a null compound statement like 


{ 2 


ALL statementss except compound statementss must end with a 
semicolon. 

In the formal definitions which follows reserved words 
are underlined and parenthesess where shownse are required. — 
Also»e “statement” implies either a statement ended by a sem- 
icolon or else a compound statement surrounded by braces. 


4.1. Null statement. 


° 
¢ 


The null statement does absolutely nothing. It 1s typically 
used to supply a null body to a WHILE statements as in 


while putchar( getchar() ) )- 


or to provide a convenient place on which to hang a label, 
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4.2. Expression statement. 


expression - 


Any valid B expression followed by a semicolon is acceptable 
as a statement. To be meaningfuls the expression will usual- 
Ly involve an assignment operation or function calls as in 


Xx = min lasb) + xs 
open( "J/myfile", "rr" ); 
+443 


but the compiler will happily accept statements which do ab- 
solutely nothings such as 


a: << ps 
opens 


1; 


Remember thats 1N Be assignment 1S an operator in an expres- 
s10ns not a statement. 


4.3. Storage declaration. 


4.3.1. Storage types. 


Before discussing the statements pertaining to storage de- 
claration or references we will briefly look at how storage 
is allocated in a B program. | 

External storage consists of the global pool of exter- 
nals declared in the manner described previously. For a 
function to use one of these externalse the name must be 
referenced in an EXTRN statement. 

Automatic storage consists of local variables which are 
created anew on the runtime stack each time the function is 
called and which disappear when the function returns. Au-~ 
tomatic storage is unique to each invocation of a function. 

Internal Clocal static) storage is allocated within a 
function body and is common to all invocations of a func- 


tion. The labels which is never explicitly declareds 1s the 


only permitted instance of internal storage. 

Constants used inside functions are allocated as inter- 
nal storages but the compiler will not accept constructs 
that would result in directly changing a constant’s value, 

Finallys there is a pool of free storage which can be 
dynamically allocated by the library function GETVEC and 
dynamically released by the library function RLSEVEC. This 
free area 1S automatically grown as required up to the lim- 
its imposed by the operating system. 
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Any identifier used in a function body must be a formal 
arguments a labels or previously referenced in an EXTRN or 
AUTO statement. The only exception is a function name used 
in a function calls since the compiler automatically types 
as external any name immediately followed by a left 
parenthesis. | 

AUTO and EXTRN statements may appear anywhere in. a 
function bodys but you should group them at the beginning of 
the function. 


4.302. Extro. 


extrn namels», name2ds aes 2 


This statement allows the function to begin using the names 
previously defined as externals (see chapter 2). Although an 
identifier may be externally declared as a vectors you 
should not indicate this in the EXTRN statements since B 
lets you use any cell in a subscripting operation. 


eres Auto. : 


auto namet> name2dCconst~exprise ees 2 


The AUTO statement is used to declare local storages which 
is unique to each invocation of the function. For example, 


auto xs 
auto i+ je xb10I)- 


A vector declaration is legal in an AUTO statements but the 


size of the vector must be a constant expressions since it 


is established at compile time, 

Const-expr is any legal combination of numeric or char- 
acter constants-e unary operatorses binary operators and 
parentheses. Make sure what you use is sensibles because the 
compiler accepts constructs Like "auto xf-1]" which lead to 
undefined results. Normallys one would expect a constant ex- 
pression which is not a simple numeric constant to involve a 
manifest constants as 1n 


MAX = 10- 


auto xCMAX*2], yCMAX + 7], 


If you need dynamic vector allocations you must use the li- 
brary funetion GETVEC to obtain it from the free storage 
area. : 

An AUTO statement which declares a vector is executable 
in the sense thats when it 18 encountered, it Initializes 
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the pointer to “nt1" words. The initial contents of an AUTO 
vector or other AUTO variables are always undefined. 

| Because AUTO variables are allocated on the stacks and 
because the stack size is finites you should be cautious a-~ 
bout declaring vectorse whose size is greater than 64 wordses 
as auto variables. Although the compiler command will let. 
you change the default stack size of 500 wordss it = may be 
oreferable to either use an externals or else allocate it 
from free storage. 


4.3.4. Labels. 


Any unique identifier followed by a colon and preceding a 
statement 1s defined as a label. For example: 


again: 
RES x 


| i 


getchar(); 


A statement may be oreceded by as many labels as appear 
to be necessarysr as 1n 


Lab1: lLab2s: lab3s: printf ("hi there”); 


4.4. Iransfer of control. 

The GOTO statement does the obvious thing. The RETURN 
statement is used to exit from a function. The NEXT and 
BREAK statements greatly simplify loop control. 


4.4.1. Goto. 


goto identifier ; 


will cause a function to transfer control to the statement 
which has the label “identifier”. 

If “label” has not already appeareds it is defined as 
one. It is a fatal error if it is not used as a label in the 
function body. 

It is legal to transfer to any location inside a func- 
tion bodys including into or out of a compound statement. It 
is almost never a good idea to transfer into a compound 
statements because the action is difficult to follow and be- 
cause it can lead to unpleasant surprises. 

Because B is a typeless Languages the compiler has no 
way of knowing whether the identifier you supply in a GOTO 
statement really turns out to be a valid label at runtime, 
so it is perfectly Legale but probably erroneouss to Say 


extrn b- 


goto bd, 
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Never try to pass a label as an argument to a function 
and use it to transfer to another function. The program will 
end up in one functions but with a different function's 
stack pointers resulting in immediate or eventual disaster. 


4.4.2. Return. 


return: + 


returo ( expression ) ; 


The RETURN statement ends the execution of a function and 
results in return to the caller. Upon returns all temporary 
storage in use by the particular invocation of the function 
disappears. , : 

The first form of the RETURN statement merely returns. 
control. The second form causes a one word value to be re- 
turned also. | 

Note that the construct 


return()-; 


is not permitted by the compiler (it gives a syntax error)... 
A simple RETURN statement is supplied implicitly at the 
end of a B function body. 
The Library function EXIT is also available, should 
your program wish to terminate execution at a point other 
than after the Last statement of MAIN, < 


4.4.3. Break. 


break » 


The effect of BREAK is to drop out of the most recent inner- 
most enclosing WHILEs FORs SWITCHse REPEAT» or ODO-WHILE 
statement. The compiler generates a fatal error if a BREAK 
statement is not inside one of these. 


4.4.6.6 Next. 


next » 


NEXT is a directive to skip all further statements in the 
most recent enclosing WHILE» FOR» REPEATs or DO-WHILE loops 
and transfer to the test which determines whether looping 
should continue. Note that NEXT is only legal in a SWITCH 
statement if the SWITCH is itself inside one of these loop- 
ing statements. 
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4.2- Conditional statement. 


4.221. Its 
if ¢( expression ) statement 


If the result of the expression is non-zeros, then the state- 
ment 1s executed. The parentheses around the expression are 
mandatory. 


IF (€ expression ) statement ELSE statement 


I f the result of the expression is non-zeros, the rirst 
Statement executess otherwise the second statement executes, 

In the case of nested IF statements where there are 
fewer ELSE s than IF se the compiler associates the ELSE 
with the closest IF at the same level of nesting. 


ft ca, oUt \ cae 4 elee a? 
resolves to 
oe 


Think of IF s and ELSE s being placed on a pushdown stack as 
they appear. An ELSE which you pull off the stack always 
goes with the next IF pulled off. 

Here are some exanples of IF statements: 


17C a@ ) ¥ Re Be 


4.6. Iterative statements. 

A REPEAT iterates a statement until a BREAK statement 
is encountered or a GOTO causes control to pass outside the 
loop. WHILE iterates a statement as long as an expression 15 
non-zeros testing at the top of the loop. DO-WHILE iterates 
a statement until an expression 7S nonzeros, testing at the 
bottom of the loop. A FOR uses three expressions to initial- 
izes test and modify in controlling a loop. 
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~6-1. Repeat. 


repeat statement 


The REPEAT merely executes the statement forever, The state-~ 
ment is almost invariably compound. NEXT and BREAK state- 
ments are legal inside a REPEAT. 


4-O-2- While. 


while ( expression ) statement 


If the result of the evaluation of the expression 1s non- 
zeros the statement associated with the WHILE is executed. 
After execution of the statements, the expression is re- 
evaluated again ands if the result is again non-zeros the 


statement 1s executed again. In other wordss while the 


result of the expression 18S non-~zerose the statement is exe- 
cuted. When the result of the expression 1$ zeros control 
passes to the next statenent following the WHILE statement. 

BREAK and NEXT statements are legal in a WHILE state- 
ment. 


4.6.3. Do-~while. 


do statement while (¢ expression +; 


The DO-WHILE provides a loop with a test at the bottom of 
the loop. It is equivalent tos. 


repeat 
{ 
statement 
if€ texpression ) breaks 
} 


BREAK and NEXT statements are Legal in a DO-WHILE 
statement, 


4.6.4. For. 


for ( expri;s expres expr3 ) statement 
The FOR statement may be used to Sete test and increment a 


variable in order to control a loop. The FOR statement is e= 
quivalent to 


Waterloo “Ge. March 1979 


i 
. 
n 
n 
1 
i 
1 
i 
i 
% 
j 
i 
eB 
n 
i 
i 
a 
i 


expr; 
while ¢€ expre2 ) 
{ 
statement 
expr3, 
} 


The first expressions which might initialize a controlling 
variables is evaluated. Thens, if and while the result of 
second expression (usually a test) 18 non-zeros, the state- 
ment 1s executed. Before returning to re~evaluate the second 
expressions the third expressione which might increment a 
controlling variables 1s evaluated. 

Both BREAK and NEXT are legal ina FOR statement. The 
effect of NEXT is to pass control to the evaluation of the 
third expression. 

Any or all of the expressions may be nulls and they 
need not necessarily involve the same controlling variable, 
if any. Note that the second expression is always treated as 
a logical expression. Some examples: 


fori i 2 OF 1 < TOs 4475 xCil = jtii: 
for({ i = 10: i <= 2} § #2) 


fort 3 = ts fj S ye #43 3 
gtiltis 2-4 ©. j 3; 


fart 2. i <. ns.) F-95427 8-208. = Tie 
NULL = Q- 
NEXT =: 43 
DATA = OF 


for( p = startlists p != NULLs p = pLNEXTIs ) 
if(€ p£LDATA] >= x ) break-s 


4.7. Switch statement. 7 

The SWITCH provides a conditional branch depending on 
the one word result of an expression. The SWITCH has the 
following formal syntax: 


switch (€ expression ) statement 
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The statement is always compound and special labels are 
allowed inside the statement to point to where to start pro- 
cessing for a given case@s as 1n 


Switch (€ expression ) 


{ : 

Case const~exprs statement 

case const-expr <3: const~exprs statement 
Dreak - 

Case <rel:.op- const-exprs statement 
/x rel op. is one of <sv <=e D=p > x/ 

default : statement : 

} 


The SWITCH evaluates the expression and compares the result 


with the constant or constant bounds in each CASE label. It 


selects a cases if there is ones and begins executing the 
compound statement at the statement immediately following 
the appropriate CASE label. If the expression result fits no 
cases, execution continues at the label DEFAULT (if supplied) 
or at the next statement following the SWITCHs if DEFAULT is 
not supplied. 

Once a case 1s selecteds execution always falls through 
into the next cases, unless a statement which alters the con- 
trol flow 1s encountered. 

Usually» a BREAK is used. It causes control to_ go to 
the statement following the SWITCH. 

A statement may have more than one label or CASE label, 
just as a label or CASE label may be followed by more than 
one statement. 

As shown aboves a CASE may be satisfied by 1) a single 
values 2) a range of values which include the endpointss or 
3) an upper or lower bound. Overlapping bounds draw a fatal 
diagnostic from the compiler. 

By const-exor we mean as usual any legal combination of 
numeric or character constantSs unary operatorss binary 
operators and parentheses which can be evaluated at compile 


time as some constant value. String constants are not per-_ 


mitted in this context. 
Any attempt to SWITCH on floating-point values will not 
works, since the generated code performs integer comparisons. 
The compiler will construct a jump table for the SWITCH 
statement if the ratio of 1) the maximum case value minus 
the minimum to 2) the number of case labels is between one 
and two, 
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As an examples here is a function which uses a SWITCH £6... 
determine if a character is legal for a B identifier. 


alophnum( c ) 
switcn¢ ¢: 2 
{ : 
case “AX s3 420: 
fk converts upper case to lower */. 
/x and falls through to return */ _ 
¢ [2 ts 
">? : 


Ot 


case ‘a’ 
case 'Q' 
case *,* 
case. 

return( c¢ J 

/x would use break if return not used */ poe 
defaults: = tn EN SEER a se 
return ( Oye. 


/* end of alphnum */ 


Ce Ee nw ON a EN EN EE 


cd 


nt perenne sat 
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2- Exoressigns. 


Expressions i1n B are constructed according to rules 
which govern combinations of operatorss identifierss square 
bracketss and parentheses. B has a large set of operators, 
which are described in this section. | 3 

Because B 1s typelesss the compiler always assumes a 
given operation on a word is appropriate. Although this 
tends to force you to do more checking yourself, it also 
gives you the scope to do almost anything you want. This 
typeless characteristic often causes trouble for beginning 
users of Bs because the compiler happily accepts possibly 
erroneous operationss such as adding one to a function name, 
Or using a pointer as a function call. Such is the price of 
freedom. 

The compiler takes no responsibility for the validity 
of expressions. There is no runtime monitoring of possible 
arithmetic overflows or faults. In the B run time environ- 
ments overflow faults are masked outs buts in the Pascal run 
time environments they are not. A divide error (like divid- 
Ing by zero) will:.result in a fault, 

Expressions are evaluated according to an order of 
binding which includes both the hierarchy of evaluation, 
which determines the order of evaluating different types of 
operatorsse and groypings which determines the order in which 
operators of the same type are evaluated. We will discuss 
the hierarchy from highest (evaluated first) to lowest and 
mention the grouping rule for each type. The results are 
Summarized in Appendix A and the explain file “explain b 
binding”. 
2el. Primary expressions. 
he primary expression is the basic building block 
used to construct expressions. It is defined recursively as 
follows: 


name 
A legal identifier is a primary expression, 

constant 3 

| Any legal constant constitutes a primary expression. 

primary(l expr ] 
A subscripting operations which is a primary expres- 
sion followed by an expression in square bracketsSs is 
a primary expression. ; 

primary( arglist ) | 
A function call operations which consists of a pri- 
mary expression followed by an open parenthesiss is a 
primary expression. The open parenthesis must be fol- 
Lowed by a possibly empty set of argumentss consist- 
ing of comma-separated expressionss followed by a 
close parenthesis, 
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( expr ) 
Any expression enclosed by parentheses which 1s not a 
function argument list is a primary expression. This 
lets you use parentheses to alter the order of bind- 
ing. 


Here are some examples of simple primary expressions: 
x getchar () (a: # b) 6 xLig 6C€xJ 


In cases where a primary expression is composed itself of 
another primary expressionre grouping occurs’ from left to 
right. For examples look at 


xCiIC}I xCI}30) 


In the first cases "x" is treated as a pointer to a vector 
of vectors. In the second caser "x" 1s treated as a pointer. 
to a vector of functions» one of which is to be called. In 
both casesy "xCil™ is evaluated firsts placed ina tem- 
porarys call it "“y"»s and then the remainder of the expres- 


sion is evaluated as "yljJ" or "“y()"s respectively. 
201-1. Subscrioting. 


Subscripting is not restricted to use with variables origi- 
nally declared as vectors. It 18 a completely general opera- 
tion which may be applied using any two arbitrary expres- 
SIONS. | 

To help you understand how subscripting works in Bs 
take a look at the primary expression 


afil 


One of the variables is supposed to be a pointers while the 


other is supposed to be an offsets but it does not matter 
which! The reason for this is that B gets a pointer to the 


eit “alij™" simpty by adding “a” and “3™ together. If the 


value of the cell is requireds the compiler gets it by using 


the pointer. Therefore it is perfectly legal to alternative- 
ly say: 


ifal 


anywhere you could have said “alfiJj". 
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As you can see aboves the general form of a_ function call 
1s: 


primary( exprils expres eseeovr Oxprn ) 


Most commonlys "primary™ is just the name of the function to 
calls» but the generality of expression is there to permit 
you construct and use vectors or tists which contain func- 
tions to be called. 

A function call primary may always be assumed to return 
a value. It is upto the programmer to make sure that a 
value is returned when one is wanted or that a value is only 
wanted when one 1s returned. 

It is also up to the programmer to make sure that a 
function is called with as many arguments as it needs. It is 


‘safe to call a function with more or fewer arguments than 


are defined for it» assuming the called function is prepared 
for such contingencies. 

Note that it is the parentheses surrounding the argu- 
ment List which tell the compiler the operation is a func- 
tion calls so they must always be present. For instances say 
you have a function called PROC which requires no arguments. 
To call ite you say 


proc() 
But if you say only 
proc 
no function catt will take places because none is implied. 


2-2- Rvalues and lyaluves. ; 

When we come to the assignment statements or to opera-~ 
tors which perform implicit assignment, it becomes necessary 
to distinguish between the address of a thing and its con- 
tents. 


An rvalue is the contents of a word. Any expression in 
B may be evaluated for an rvalue. For example, the rvalue of 
a subscripting operation is the word addressed by the sum of 


pointer and offset. 


Everywhere in this manual where we say "expression"s we 
mean an expression whose result 1s some rvalue. 


An lyvalue is the address of a word. Only a names a sub- 
scripting operations or a primary expression prefixed by the 
unary indirection operator ‘'*' may be evaluated for. an 
lvalue. The lvalue of a  subscripting operation is. the ad- 
dress formed by the adding pointer and offset. 
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It 38 convenient to think of an lvalue as an expression 
which is legal to the left of an assignment operator and of 
an rvalue as an expression which is legal to the rights as 
Long as you remember that both may also appear in other cir- 
cumstances. 


Context determines whether an expression 1s evaluated 
for its rvalue or its ltvalue. For examples look at the as- 
signment 


aC3jJ = 2% x 


The expression on the right yields an rvalue which 7s the 
sum of the contents of "x" and the constant "2", “al3J" must 
be able tos and doeses yield an lvalue which is the address 
of the place to put the sum. 


Converselys it is illegal to say either of 


6 = x 
(a + & 3 ¥ 


because the expressions which are on the left of the assign- 
ment operator are not permitted to have an lvalue. If they 
could have an tvalues you could then in the first case 
change the value of the constante or in the second case make 
a meaningless assignment. 


8.3. Unary operators. 

A unary operator acts upon a unary expression to 
transform it in some manner. A “unary expression” is either 
a primary expression or a primary expression already modi- 
fied by one or more unary operators. In the definitions 
belows "rvalue” or “tvalue” must be aunary expression, 
Unary operators are applied from left to right. Except for 


the unary indirection operators the result of applying a 
unary operator is always an rvalue. 


The following unary operators are defined: 
#rvalue | 
Assumes the value of the expression to be integer and 
converts it to single precision floating point. 
H#rvalue 
Converts single precision floating point to integer. 
“rvalue 
One's complement. Converts all zero bits of its 
operand to ones and all one bits to zeros. 
-rvalue 
Results in the arithmetic negation (two’s complement) 
of the operand. 


March 1979 =-27- : Waterloo 


—a 


al 


Hervatue > 
Results in the floating point negation of the operand 
word. 

'rvalue 
Logical not. The result ts zero 3f the operand ts 
non-zeros otherwise, the result is one. 

x*rvalue 
The indirection operator. Takes the rvalue but uses 
it as an lvalue. This is the only case in which a 
unary operation returns an lvalue. Thus) any primary 
expression prefixed by a"*" may appear on the left 
hand side of an assignment. "*6 = x™ stores the con- 
tents of x in location six. "“y = *x™ stores the con- 
tents of the word pointed at by x into y. 

&l value | 
The address operator. Forces the program to generate 
the lvalue of the expressions then use it as_ an 
rvalue. For instances "&x" is an rvalue which con- 
tains the address of x in the lower 18 bitss while 
"26" is tllegalse because "6" may not have an lvalue. 

++lyvalue 
Adds one to the rvalues before using it. Each of the. 
auto increment/decrement operators require an lvalue 
as its operand. An lvalue is requireds because of the 
implicit action of assignments but the result is al- 
ways an rvalue. 

lvaluet+ 7 

Adds one to the rvalues after using it. 


etatvalue 
Subtracts one from the rvalues then uses it. 
Lvalue-- : 
Subtracts one from the rvalues after using it. 
aprimary 


The at~-sign operator is used to force the use of 
Honeywell hardware indirection, Its effect is to OR 
the indirect bit into the Last generated instruction 
for an expression (rvalue or lvalue). The instruction 
affected is usually a load or store. It was most com- 
monly used to access characters using talliess by in- 
directing to a word with tally modification and the 
address of atally word. Normallys you should not use 
+t. 
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There 1s a fundamental relationship between the 
operator and subscripting which should help you understand 
how addressing works in Be. The following are exactly e- 
quivalent everywhere: 


alb] <=> *Catb) oe S> blaJl 
To be able to write or understand B programss it is vital 


that you understand the validity of this relationship. 
Here are some examples involving unary expressions: 


++ 3 
Adds one to the value of “i. Frequently used short- 
“Nand for "=e: i +. 1"; 

atbifcj++ — 
Forms an address by adding together "a" and "b", 


picking up the word pointed at and then adding "c™ to 
the contents. It is equivalent to "“*(*la + b) + cd”, 
If this were part of a tlarger expressions the word 
pointed at would be loaded into a temporary, Then the 
contents of the addressed matrix element is Incre- 
mented by one. 
Salij — 
Forms the address of the cell “aliJ"” by adding the 


ee 88 se ee 


values of a”) and I". OTRat ¥8$%  3t FS evaluated as “a 
Se ale 
y = *(C&x) 
/ The verbose way of saying "y = x", 
yxy = «ptt 


The word which word pointer "“p" points at 18 copied 
into “x",» then "p" is incremented by one to point at 


the next word. That ise "p™" is useds then increment- 
ed. 

Xx = +#%*p, 
The word pointed at by "p™ is incremented by one and 
then copied into “x"™, 

kttp = x 


The contents of "x" are copied into the word pointed 
at by "p", but only after "p" has been incremented by 
one to point to the next word. That iSs "p" is first 
incrementeds then used. 
*6 = 2 
Places the vatue two in tocation six... "*6": 1s the 
Same as “OC63" or “6(01". This tine of construct. 4s 
used to access locations in the slave program prefix. 
biatbs +. 34 
Gets the contents of "“albJ]" into a temporary and adds 
one to the ‘temporary to get the subscript. The con- 
tents of "x" and the subscript are added together, 


yielding the address of the element of "x" to. be 
used. 
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2-4. Binary operators. 

All other operators are binary operatorsse which means 
they require both a left and aright operand. Each operand 
must be an rvalued expression, 

With one exceptions the order in which the two operands 
are evaluated is undefineds so don't have the evaluation of 
one side depend on a side effect generated by the other side 
Cin a function calls for instance). Logical operators are 
the only exception. Their operands are always taken strictly 
trom teft to right. 

The code generated for floating point operations’ is 
corrects but not blindingly efficients since the compiler 
generates a separate load and store for each use of a 
floating-point operand. Howevers it is there if you need it. 
For non-casual use of these operatorss it 1s probably better 
idea to either call a Fortran or Pascal routine to do the 
jobs or else program in some other language. 


Q~2- SHift operators. 


expr << expr : 
The teft operand is taken as the one word bit pattern 
to be logically left shifted. The right operand sup- 
plies the number of bits to shift. If negatives or 
greater than 127. the result is undefined. 

expr >> expr 
Logical right shift according to the same _ rules. No 
arithmetic right shift is defined in the languages 
but you may use the library function ARS. 


Shift operators group from left to right. 


Oos6,. Bitwise ang. 


expr & expr 
The "&" operator takes the bitwise "and" of its two 
36 bit operands, If bit. 1 of both operands 1S ones 
then bit 1 of the result is one. Otherwise bit 1 of 
the result 18 zero. 


2-2. Bitwise exclusive or. 


expr ”~ expr 
Takes the bitwise “exclusive or“ of its two 36 bit 
operands. If bit 7 ¥$ On in ones but not in the oth- 
ers then bit 1 of the result is on, 
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2-8. Bitwise or. 


exor | exor 
This take the bitwise "or”™ of its two operandss such 
that if bit 1318 on in either of the two operands or 
boths bit 1 in the result 3s on also. 


The following is a Summary chart of the results of bit- 
wise operations. The table shows the effect of each opera- 
tion on one bit. 


operands results 

a b and or exor 

0 0 0 0 0 

0 1 0 1 9 

1 0 oe 1 4 = 
1 1 4 1 0 


The three bitwise operators group from left to right. 


5-9. Multiplicative operators. 


expr / expr 
Integer division of the first integer operand by the 
second. Will result in a divide check abort if the 
right operand is zero. The result is zero if the left 
operand is less than the right. The result is trun- 
cated towards zero if the right operand does not 
divide evenly into the left. The result is positive 
if the operands are both positive or both negatives 
otherwises, it 18s negative. 

expr 4 expr 
Results in the integer remainder of the integer divi- 
sion of the first operand by the second. [If the 
remainder is non-zeros it has the same sign as the 
left operand. 

expr * expr 
Integer multiplication. 

expr #/ expr 
Single precision floating point divide. 

expr #* expr | 

© Single precision floating point multiply. All float- 
ing point operators assume floating-point operands. 


Multiplicative operators group from left to right. 


Soeur arerreee re? 
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2-10. Additive operators. 
These provide integer or floating point addition and 
subtraction. 


expr + expr 
Integer add, 
expr ~ expr 
Integer subtract. 
exor #+ exopr 
Single precision floating point add, 
expr H#=- expr : 
Single precision floating point subtract. 


Additive operators group left to right. 
2-11. Relational operators. 


expr = 
Eq 
j 


= expr 
Wats 3: 
= expr. 
Not equal. 
expr < expr 
Less than. 
expr <= expr 
“Less than or equal, 
expr > expr 
: Greater than. 
__expr >= expr 
. Greater than or equal, 


expr 


The result is one if the given relation between two integer 
operands is trues and zero otherwise. 


s The following operators perform the same function for 
floating point operands: 


#== H's ace e<= “> #>= 


__2-+1¢- Logical and. 


exor && expr 
The result is an integer one if the result of both 
expressions 18 non-zeros and zero otherwise. 


The left-hand expression is always evaluated first. If its 
— result 15 zeros the result of the expression is zero and the 
= fight~hand expression is not evaluated. 


bat 
ee G 


ee rs 
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expr Il expr 
The result 18 an integer one if the result of either 
expression or both is non-zeros and zero otherwise. 


The left-hand expression is always evaluated first. If the 
result.is non-zeros then the result of the expression is 
non-zero and the right-hand expression 1s not evaluated, 


2-14. “Query” operator. 


exor!l ? expr2 : expr3 
The first expression is evaluated. If the result is 
non-zeros the second expression is evaluated and re- 
turneds while the third expression is ignored. If the 
result of the first expression is zeros the third is 


evaluated and returneds while the second is ignored, _ 


This is analagous to "if€ expr1 ) expr2s else expr3", 
but has the advantage that 1t may be used 1n an expression. 
For examples a_ function to calculate the maximum of two 
numbers might be coded as: 

max’ ar bd feturnt a.> & 2? @ : b Ge 


Grouping is teft to rights so that 


is equivalent to 


a? 6 : teteve) 


§.15. Assignment operators. 


lvalue = expr | : 
Takes the one word result of the evaluation of “expr” 
and stores it in the word addressed by the lvalue. 


tvalue <op>= expr 
Is equivalent to the assignment. 
Lvalue = rvalue <op> ( expr ) 
where <op> can be any one of 
*. gf a en oe — ea Sn | 
Note that neither floating point nor relational 
operators are included, 
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For examples 


1s the same as 
xX = x*la + be 
In all casess the expression is evaluated first, even though 
the operator in the assigninent may have higher’ binding 
strength than an operator in the expression. 
Assignments group right to lefts 


¥- sy Sly 


1S taken as 


x = (y = 0)3 


Remember that assignment is an operations not a state- 
ments and so is legal almost anywheres including conditional 
expressionss such as 


Att Gs = ylitel) ee 2 3... 


Note that parentheses are used in this case to alter the 


order of precedence. These are required in this case because 


the assignment operators have the lowest precedences which 
means that they are evaluated last. : 
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&. laplementation-dependent information. 


The information in this chapter is subject to change. 


6.1. Linkage conventions. 


The B compiler’s mechanism of performing a function 
call is rather different from the standard Honeywell calling 
sequence. In this chapters we will describe the calling con- 
ventions in details so you can attempt to write or under- 
stand functions written in GMAP for the B environment. 

The stack format described here is also used by PAS- 
CAL/66. 


Q-1.1. Function call. 
The standard B function call looks like 


tsxl sub 
zero Sen 


where "s 7S amount by which the stack pointer should be 
bumped and "n" is the number of words of arguments supplied, 
The compiler generates these numbers for B functions. 

When a B function is runnings its stack pointer points 
to a word of return information. Just below the Stack 
pointer are two wordssy which are used by any function which 
is called from the current function. Above that point 15 a 
fixed size area for arguments and for AUTO variabless all 
addressed relative to the stack pointer. Stack space above 
the AUTO variables is used to hold temporaries created dur- 
ing expression evaluation. When one function calls another, 
the stack pointer 1s moved so the callee does not affect the 
state of the caller, 

Before executing the TSX1 Instruction to transfer to 
the functions the catler must first set up the argument 
values. The first and second arguments are loaded into the A 
and Q registerss respectively. Other argumentss if presents 
must be placed in the stack in such a way that they are 
available to the caller once the stack gets bumped. This 18s 
shown tn the next section, 


Scsiecs. EDLCY. 


The general convention for a subroutine entry looks like 
this: 
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symdef sub 
Symref ,entry 


Sue. if a x +4 value of function name 
tsxQ sentry adjust stacks save linkage 
zero frmedbg frame sizes debug table 
staq Te? first two args passed in the AQ 


"Erm" indicates the maximum number of words of stack that 
will be used by the function. A pointer to this’ word is 
saved in the stacks so thats if there occurs an asynchronous 
event (such as a fault), it will be possible to locate the 
top of the stack. "Frm" is also used in the check for stack 
overflow. "Dbg" is a pointer to the local debug symbol 
table, if presents or else zeroe if note. It 1s used by the 
debugger and by the profilers .PROFILE. : Se 
The code executed by .ENTRY (without the stack overflow 
check) looks like this: = 


stx1 “Test return for traceback 

stx ~2erl actual return address 

sxl0 ~Te27 save pointer to frame size 
Ldx2 0-1 get "s" from function call 
sar? Or2r7 save old stack pointer 

awd Or2r7 bump stack 

tra 120 return 


There are two things to notice about this sequence of code. 
Firsts note that the return address is stored twice. This 
atiows the actual return address to be modified if it is 
necessary to intercept a function returns while still allow- 
ing the debugger to print a correct traceback. SETEXIT and 
ALLOCATE are examples of library functions which set up in- 
terceptions of function returns. Seconds note that return 
information is saved in the caller's stack frame. This means 
that certain tlibrary routines can avoid the overhead of a 


‘call to .ENTRY but still get access to two words of stack 


space "for free”. 

Register usage conventions are as follows. Address re- 
gister seven is reserved for the stack pointer, Index regis 
ter six is reserved for the coroutine package. Address re-~ 
gisters four and five are reserved for use by the i/o pack- 
age. Index register five may be useds as long as its value 
on entry 1s restored on return, The remaining registers 
(arO-ar3,s xO0-x4) may be used freelys but note that a func- 
tion which does not invoke .ENTRY is responsible for 


preserving the return address in index register one. YOu can 


use index register seven freelys except in the Pascal run 
time environments in which you may use it freely only after 


copying over the display it points to. 


By conventions the first two arguments are passed in 
the A and @ register. It is the responsibility of the called 
function to store them if necessary. 
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The hardware will only allow a STAQ instruction to work 
correctly if the address of the store is at an even word 
boundary. To ensure that the STAQ will works the stack 
pointer is always initially set to an odd addresses and must 
always be incremented by an even amount, 

Once the STAQ is dones the stack is organized as fol- 


lows: 
~2erl -> used in next call 
all IO a -> used in next call 
Ore? -> previous stack pointer 3 
Tool -> first argument (Cinitially in A register) 
Crol -> second argument Cinitially tn @ register) 
Neosl -> nth argument (placed in stack by caller) 


n+leel => start of auto variables and temporaries. 


ws 


6-1-3. Exit. 


when a B function has done its jobs it returns using the se- 


quences 


symref .retrn 


tsxO0 eretrn (Lar? Over? - restore stack pointer) 
rem (ldx1 -277 - get return address) 
rem (tra 11 - return) 


Prior to thiss the function may load a one word value into 
the Q registers which becomes the value of the function 
cat, 

A TSXO instruction is used so that the interactive de- 
buggers if in uses can determine the address at which the 
function returneds in order to find out the name of the 
function returning. 


6.2. Internal representation of obiects. 


The material in this section is intended to help you 
understand how the code generated by B works internally. 

The value of a function name is an external word con- 
taining a transfer instruction with the address of the first 
word of the function body in the upper 18 bits. Transfer of 
control to a function body always occurs by transferring to 
a words which is expected to contain a transfer to the start 
of the actual function body. 

The value of a label is a word containings in the upper 
18 bitss the address of the place to go to in the function 
body and zeros inthe lower 18 bits. The transfer involved 
in a GOTO occurs indirectly through the label word. 

The value of a pointer or address is a words whose bot~- 
tom 18 bits are taken as an address. 

The value of string constant is a pointer to the text 
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ia the 8 Library. 


One of the big advantages in using B is the availabil- 
ity of a targe library of useful functions which simplify 
your programming problems and also supply a_ reasonable in- 
terface to the GCOS/TSS environment. 

Every B library function you could reasonably expect to 
use has an explain file under “explain b lib”. There is also 
an index of all documented routines. ~ | 

Only the routines you need to get started using B will 
be discussed here and even then not all options may be 
treated. : - 


this section by showing an assignment to indicate a value i: 


returned. Alsoe some functions are called with a variable — 


number of arguments. If you want to use an optional argu- 
ments you must usually also specify any preceding optional 
arguments also. Optional arguments are shown enclosed in 
square brackets. For examples if a function is shown as 


return = func( argi Ce arg2ds arg3]) )-s 


and you want to use "arg3", then you must also use "arg2", 
Sometimess as you will seer the first arguments usually a 
"unit™’,s may be optional. In this cases the called function 


craftily examines the first argument to see if it 18 a4 


9 @ 


muomber valid for “unit”"s if +t 18 note #t adjusts if argu- 
ment. references accordingly. 


cules «BSET ~ fedifection of ifs. 


Before your main program is entereds the run time inin~ 
tialization routine calls a function named .BSET which 


"oredigests” the command line for the user program and also 
sets up any "redirection of i/o" requested on the command 
Line. , 

In batches .B8SET Looks for the command Line on filecode 
CZ. In your jcls you might have something like 


$ data ez 
command arg arg2 ees. 


BSET breaks the command Line up into “arguments”. An 


argument is either a string of non-blank characterss a quot~ 
ed strings or a redirect request. | 
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Some functions may return a values this is indicated in 


A redirect request has three forms: 


<filename | 
~-BSET will open the file for reading on B unit QO. In- 
put for unit 0 will come from this files rather than 
the terminal. 

>filename 
The filename +s opened for writing. Output to B unit 
1 will go to this files rather than the terminal. 

>>filename 
Same as aboves except that if the file already ex- 
istSe output 18 appended to the file. 


A quoted string is delimited by either single or double 
quotes. To get a quote inside a quoted strings either use 
the quote which is not the delimiter or else put in two of 
the delimiter characters. ee 


-BSET collects the arguments which are not redirect re 
quests and builds a vector of pointers to those strings. 


MAIN 1s Later called by 
_ main(€ argces argv )- 


where “argc™ is the number of arguments collected and "argv" 
is a pointer to the vector of strings. “argvlargc]” always 
contains the constant -1. 7 

In additions .8SET builds an external vector called 


—,ARGTYPEs each cell of which contains a character giving 


some indication of the type of argument in the corresponding 
ARGV string: 3 


type character 
string fee 
string in single quotes ‘ae 
string in double quotes i= 
-option | ‘_! 
toption ‘+? 
possibly signed number | “O° 
string with = in it ‘=' 


For examples look at the command Line 


go -r /myfile "a string" >beout 


MAIN will be called with ARGC set to fours since ">b.sout”™ is 


mot inctuded., Ati writes om wait 1 witt go to the fite 


_b.outs which is created if mecessary. The ARGV and .ARGTYPE 
vectors are set up as follows: 


argvl[0] = "go" earagtyplLOj = * ° 
argvllj = “-r* sargtyplij = *=-* 
argv(2] = “/myfile” saraetvyeccs. = * * 
arav(3] = "a string” saretynt3i.= *"* 
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argv[4j] = -1 


and the contents of the remaining elements of the ARGV vec- 
tor are undefined. 

If you do not want to have .BSETs simply supply your 
own function definition of "™ beet Qi" which will replace the 
library version. 

Normallys, howevers you will want .BSETs because it 
greatly simplifies the task of handling command lines. In 
facts there are even more powerful facilities built into 
-BSET for scanning command lines with arguments of specified 
types. As wells you may call .BSET to scan an arbitrary 
string. For full detailss see the explain file “explain b 
[Fb sbset". 


2.2. Introduction to input/output. 

The largest class of functions inthe 8 library are 
those concerned with input and output. Sequential t. 
routines will reads and convert to ASCII if necessary,s ane 
sequential file In standard'system format, including media 
O- 2 or. 3 BCD» media 5s 6 or 7 ASCII and media 1 compressed 
source decks (comdks). Output is ASCII (media 6) unless spe- 
cial precautions are taken, 

The i/0 package will create output files if necessary 
and “grow” them as required up to their maximum size or to 
the Limit of the file space quota for a userid, 


foes. UVoits. 


A B program may have several files open for reading or writ- 
ing at the Same time. Each file 1s associated with a number 
called a “unit”, to which every i/o call implicitly or ex- 
olicitly refers, 

: There are five units whose function 1s. predefined and 
may not be altered by the user. 


“5 
This is an input unit whose origin is always the ter- 
minal in TSS or file code I* in batch. It may be used 
to force reading from the terminal or fite code Its 
even though the standard input) may have been 
redirected to come from a file. Normallys you should 
use unit zero instead. 


This 18 an output unit whose destination 1s always 
the terminal in TSS or file code P* in batch. It is 
most often used to avoid possible redirection of i/o 
by forcing error messages to appear ona hard copy 
device. Normally you should use unit one instead. 
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Used for console input in batch only. 
of 

Used for console output in batch only. 
-1 


In TSS all output directed at this unit behaves as 


1f it were typed at command level. In batchs output. 


to unit -~1 goes to the execution report. 


Unit zero 1s initialized as the standard inopyt unit. In 
TSS this 1s the terminal but input may come from a file if 
redirection of i/0 1s used. In batch, reads on unit zero 
come from file code I*, if it is defined and 3% input was 
not redirected. If I* is not present and there is no input 
redirections unit zero is placed in the end-of-file condi- 
— Romteleiol 

Similarlys unit one is initialized as the standard oyt- 


put unit. In TSS» this 1s again the terminal and is subject 


to redirection of i/o. In batche output to unit one goes to 
the printers unless redirected. 

Units two through 44 may be assigned by or to yous us- 
ing the file opening calls usually to permanent or temporary 
disk files. It 18S permissible to open units zero or ones but 
the usual practice is to leave them alones so they” may be 
redirected. 


LeZege UNOit opening. 


Before any i/o may be performed on a unity it must be ini- 
tialized by a call to OPEN», which is of the following forms 


ret = open( Cunits] filenames action )- 


Normallys “unit™ 1s not supplieds and OPEN finds a free 
unite which it returns. If you do specify a units and that 
unit 1s already opens The state of the previous unit is 
Saved ona stacks when the current use of the unit 15 
closed» the previous state is restored and i/o may continue 
on that unit as if there had been no interruption, 

"filename" is a pointer to a string containing the usu- 
alt catatog/file string (e.9. “fbhaggins/s/test.b"). An alt- 
name in quotes 1s usedsv if present. Permissions are effec- 
tively ignored, 

"action" is also a pointer to a string containing char- 
acters which specify the access permissions required and the 
type of i/o to be done on the unit. 

"ret" is the value returned by. OPEN. If non=-negatives 
the open succeeded and "ret™ contains the number of the unit 


just opened. "ret" is negative and no unit is opened if 


there was a file access error or if there was an OPEN error. 
, Although not quite all of the various’ things accepted 
by OPEN are dealt with in this chapters they are treated 
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Access actions: Most of the times the only thing you 
need to specify to OPEN is how you want to access the unit. 
Here are the alternatives: 


r 
The 'r', for reads means you want to read on the un- 
5a" 

W 
The ‘w', for writes means you want to write on the 
unit. 

a 


The ‘ats for appends means you want to ewrite on the\ 
units but by appending to what 1s. ayer there. I f 
there is nothing already theres or if appending 1s 
inappropriates the result is the same as if you had 
used the ‘w' action. oe 


For ordinary sequential file processing» one of the above is. 
the only action you need usually specify. 


Mode actions: OPEN offers three ways to specify the 
mode of the unit being opened. They are as follows: 
b : : : 
The ‘'b*. for block i/or requires that the unit being — 
opened be a random access file. 


This 15S used for so-called “string 1j6”., - -The 
"filename” argument is taken as a pointer to. the 
start of a block or words in memory. The stream i/o 
functions will place characters into this. block of 
memorys rather then transmitting them to a file. 


Open the file according to its mode. It is then up to 
the program to determines with the help of the func- 
tion FILDES+s whether the file is random or sequential 
-and then make whatever i/o calls seem appropriate. 


If none of these is supplieds the assumption is that a file 
is wanted and that it should .be sequentials as _ is usually 
the case. 


: Error actions: Normallys OPEN never returns an error 
statuss since the default action 1s .to abort the program 
with a reasonably understandable error message. 

The OPEN function lets you specify options which allow 
you to handle either file opening errors or file i/o errors 
or both. These options are in the form of characters which 

may appear in the action string: 3 
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e 
Arranges things so that a negative status is returned 
on an i/o error. | 

f 
Sets things up so a negative status is returned on an 
OPEN or file access error. 

m 


Normally» when an error status is returneds no error 


message is printed. The inclusion of the ‘m' option 
in the action string will cause the appropriate 
routine to display an error message before returning 
bad status to the caller. It has no et tect 1f neither 
the ‘et or ‘*f* action is used, 


For instances if you said 


open ( "1 ayes 


and "/myfile” could not be. opened with read permissions OPEN 
would print an error messages then return bad status to the 
callers 

In the case of OPEN errorss you will most Likely get 
back a number with is the negative of the file system error 
status. For examples OPEN would return -5 for "permissions 


denied". In additions OPEN itself is liable to return any of 


the following special error statuses: 


=e -~64 - too few arguments 
a -65 - no free unit 
. -~66 - open append error 


File access conventions: There are a number of file 
access/create conventions for TSS which you should be aware 
of: | 

1. Search rules A Quick agcesSs name 18 one whith con 
tains no slashes or dollar signs and does not. have an alt- 
name. It must also be less than nine characters longs if 
nots it is considered to be in-error. If you are opening a 
file and the name is a quick access name (e.g. "b.out”")s the 
file accessor first searches the AFT for a file of that 
name. If not founds the file accessor searches for a file of 


that name in the User-Master-Catalog of the current userid. 


If the file name is not of the quick-access forms, it 18 as- 
sumed to be the name of a permanent file, 
2e Create rule: If the search fails and the request 15s 


_to write or appends OPEN will attempt to create the file. If 


sthe tite name is of the Quick access forme OPEN witt: try to 


We teate it as temporary, otherwise it tries to create a per- 


manent file. | 
Se AFT rules If the file was already tn the AFT when 
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accessed, or if the file is a temporary file created during 
the accesses it is left there when. the unit is closed. If the 
file was not In the AFT Initially» and the file 7S per- 
manents it is removed from the AFT when the unit is closed. 
You may override this by including in the action= string 
either the character ‘t’ (for transient) to force deaccesss 
or the character ‘k' (for keep) to force the file to be kept 
77? the AFT. 


£.2-3- Unit closing. 


When you are through with a units you may want to close it 
explicitly by calling CLOSE: 


close( unttia-e 


For sequential stream output unitss CLOSE flushes the output 
buffer if necessarys with an end-of-file mark written if ap- 
propriate. A unit associated with a disk file has the file 
deaccesseds if required. CLOSE releases the i/o vector after 
checking to see if. there was a prior use of the unit which 
had been interrupted and saved. If there wass it is restored 
and i/o may then proceed on that unit as if there had been. 
no interruption; otherwisers the unit is free for further al- 
location. 

When your MAIN function terminatess or when” you call 
EXIT directlys all open units are closed automatically. Note 
that if you hit breaks things are set up to call EXITs un- 
less your program has’ established its own break = handling 
procedure. : : 

Any attempt to read data from ai unit which is not open 
results in the library routine called returning a_ value 
which indicates nothing happened. Similartlys output to a un- 
it which is not open tends to vanish. 


Since some input/output calls may not specify a unit direct- 
ly» the i/o package maintains a default input unit and a de~ 
fault output unit to which these calls implicitly refer. 

Initially» the i/o package is set to read from the 
standard input (unit zero) and write on the standard output 
Cunit one). 

Any successful call to OPEN changes the default input 
or output unit. 

A library function which takes a unit as one of its ar- 
guments will change the reading/writing unit for the dura- 


ston of the catl and restore the previous value before re-~ 


turning to the caller. 
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User control over unit switching 1s supplied by 
old.eunit = .eread( ECnew.eunit] )- 
If “new.eunit” 18 givens it becomes the current read 
unit. The number of the old read unit 1s returned. 


old.unit = ,write( Cnew.eunit J > 


Works the same way as .eREADs except that it applies 


to the default write unit. 


is3- S$eQuential sireanm 1/o. 


This section describes the body of routines oriented towards 
handling input/output on terminals or standard system format 
sequential files. 


The i/o package reads almost any media and arranges 


things so that the using program sees only a stream of ASCII 
characters. For instances BCD printer slews and strange es- 
capes in media 3 files are correctly detected and converted 
on inputs as are ASCII slews in media ? print image files. 
Compressed source decks are handled correctlys but the way 
it handles object decks is probably not very useful. Media 0 
1s always taken as variable-length BCD. 

On outputs the i/o package writes media 6 ASCII unless 
special action is taken as described in the explain file for 
OPEN. If writing to SYSOUT in batches output is media three 
(BCD printer format). 

You have the option of opening a unit to reads to write 
or to append as follows: 


unit = open( filenames, "r"™ ); 
open a unit for readingsr requesting read/concurrent 
permission. 

unit = open( filenamer “"w" )2 
will open a unit for writing, requesting 
write/concurrent permission. 


unit = opent fitename, “a J. 
will open a unit for writing so that data written by 
the program is appended to the end of the file. If 
the file is null to start withs OPEN treats the si- 
tuation just like a regular open for writing. 
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fis3s1i. Terminal vs file. 


There are a few special features of and differences between 
file and terminal i/o of which you should be aware. 

A logical record consists of a string of characters 
followed by a"“record terminator™s which is one of **n', 
tar", or **xf*, Of theses **n* 35 Never present on an toput 
filer insteads the ‘xn* is automatically supplied by the i/o 
package to indicate the end of a _ record. On input from a 
terminals you separate logical records (lines) by using 
either the "return" or "Line-feed” key. 

End of file ona file is signalled by the presence of a 
special record at the end of the file. End of file on a ter- 
minal is signalled by a tine whose first (Cand usually only) 
character is an ASCII file separator (FS ~ octal 034 ) char- 
acters the same as is used by TSS GFRC. On most ASCII termi- 
nalss including the Teleray and Volker-Craigv a FS character 
is transmitted by typing the ‘cntt* and "\" (backslash) keys 
sSimultaneuslys followed by a carriage return. On certain 
otherss you get an FS by typing “*enti*s ‘“‘shttt*s and *t*. 
You can't signal end of file ona 2741, | 

Sequential file output is written in GFRC standard sys- 
tem format with 320 word blocks. An end of Line ('kn") char- 
acter written to a sequential disk file signals the end of a 
record but is not itself placed in the records all other 
record terminators do get written out. A new logical record 
is started following the receipt of any record terminator. 
If more than 1272 characters are written in a_ logical 
records the i/o package will generate partitioned records to 
permit the logical record to span more than. one physical 
block. A 320 word buffer is written out only when it is 
necessary to start a new buffer or when CLOSE is called, 

Terminal output is buffered by TSS. Howevers if your 
program issues a_ read from a terminals the i/o package ar- 
ranges that all output sent appears on the terminal before 
7t ts “untocked" for input. 

When writing to the batch consoles a ‘'*v' is translated 
co: 6" 4n* s,s but does not cause the current line to. be 
flusheds in order to let you either write a couple of Lines 
or else write a Line and then read a lines, without having to 
worry about some other process affecting the console between 
writes or between read and write. ; 
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char_got = getchar() 
Returns the next character from the current read un- 
it. Returns the character '*0° if the current reading 
unit is closed or at end-of-file. Most of the input 
routines described here behave as if they make re- 
petitive calls to GETCHAR, 


char = ungetc( char )- 
Sends a character back to the current read unites so 
that the next call to GETCHAR will return the last 
character put back. 


char = getc( unit )-, 
Same as GETCHARs except the reading unit is switched 
to "unit”™ for the duration of the calls then re- 
stored. 


char_put = putchar( char ), 
Sends the character supplied as its argument to the 
current writing unit. PUTCHAR also returns its argu- 
ment word as its value. The argument word may actual- 
tly contain up to four non-zero characters. PUTCHAR 
“will output as many characters as there are _ in the 
word. 
er en i  T—————§ SS 
Same as PUTCHARs except PUTC switches writing units 
for the duration of the call. 


string = getstring( Cunits] string Cemaxl] ); 

GETSTRING gets the next line of inputs or the 
remainder of the current line of input if GETCHAR has 
already been called. The newline at the end of the 
Line is not returned- instead it 1s replaced by a 
"*O0" to mark the end of the string. "string" is taken 
as a pointer to a vector long enough to hold the 
string. "unit" is used if supplieds otherwise’ the 
current read unit is used. If "maxl" is givens only 
the first "maxl" characters are returneds with a ‘*0' 
tacked on to the end, If the unit is closed or at 
end-of-files GETSTRING returns zeros otherwise it re- 
turns “string”. The string is the nullstring if a 
line contains only a newline. If GETCHAR was not 
called» GETSTRING has the effect of returning the 
next line of input from the terminal or the next log- 
ical record from a file. 
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string = getline( CLunits] string Es maxlen] )-; 
Same as GETSTRINGs except the line terminating ‘'*n' 


is included in the strings just before the string 
ending ‘*0O*, 


printf(€ Cunits] format-strings argts arg2r ewes )2 

PRINTF 3s the most frequently used means of doing 
output in the 8B Library. If "unit" is not supplied, 
the default writing unit is used. If "unit" is given, 
PRINTF temporarily switches writing unitss but re- 
stores the original state upon return. "format”™ is a 
string describing how the arguments are to be output. 
It may contain any combination of literal characters 
and formats. A format is of the form "Z%nnx",s, where 
“nan” 45 an optional counts and "x" is one of the fol- 
lowing characters: 

b - The corresponding argument is taken as a 
pginter to a string of BCD characterss which is 
to be translated to ASCII and printed. Since BCD 
strings do not have a string terminators a count 
of six is assumed if not supplied. Trailing 
blanks are stripped, 

c ~ The corresponding argument is printed as an AS- 
CII character. The count option is not applica- 


ble. The argument word may actually contain up 


to four non-zero ASCII characterss which will be 
printed, 

d - The corresponding argument 1s taken as a de- 
cimal integer which is converted to a string and 
outout. 

f ~ The argument is taken as a floating=point. 
number to be converted and output. If your pro- 
gram does not use at least one floating-point 
operators you must include an “extrn floats" to 
force the toading of the floating-point output 
routine. 

o ~ The contents of the argument word are output in 
octal. 

s ~- The corresponding argument 1S taken as a 
pointer to an ASCII strings which is transmitted 
to the output unit stripped of its trailing 
PeO" 

If a character in the format string 1s not part of a 
formats it is printed as it appears. If a format does 
not have a corresponding arguments 1t 18 printed as a 
Litéerat string, To print out ‘‘*2%*s you must use “22°. 
There is more to PRINTF than is given heres for full 
details. see the explain file “explain b lib printf”. 
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String = putstring( Cunites) string Comaxi] )3 
Works in much the same way as GETSTRING. The ‘x0! 
which marks the end of the string is not output. If 
you want to write out a logical record and the string 
to be output does not end with a ‘'*n', you should 


usually follow a call to PUTSTRING by a 
“putchar C' ent) 2", 


number = getnum()-; 

GETNUM returns the nexts possibly signed integer 
number from the input stream. It calls GETCHAR until 
it has skipped over all blankse tabs or newlines. If 
the character is not a digit or a signe zero is re- 
turneds indicating no number was found. If a sign was 
founds and the next character is not a digits zero is 
returned again. Otherwise it collects numeric charac- 
ters until a non-digit is founds then converts the 
numeric string it has collected to binary and returns 
that number as its value. The external GETN.LA has the 
value 1 1f a valid number was found. The external 
GETN.L contains the last character read, 


putnum( number )- | 
PUTNUM converts the assumed binary integer which is 


its argument to a character string and directs the 


string to the current output unit. 


etatus = eof(- Cunit] 37 

= Returns a non-zero vatue if “unit” is at end of file. 
If “unit™ is not givens the current reading unit is 
used. Once a unit 38 opens end of file is. set only 
after an attempted read results in the detection of 
that condition. If "unit" is givens and the unit is 
an output disk files a logical end of file is written 
and a new block begun. 


There are a few other routines which must be mentioneds but 
which will not be described in detail here. READF does for- 
matted inputs somewhat Like PRINTF in reverse. It also sup- 
plies the only convenient means of reading in a floating 
point number. GETNUM and PUTOCT can read or write octat 
numbers, 

GETREC and PUTREC allow you to obtain/transmit a logi- 
cal records including record control words without any in- 
tervening processing by the i/o package. You must understand 
Standard system format before you attempt to use GETREC or 
PUTREC. 
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f£.4. Random file i/o. 

When using random-access files» your program is 
responsible for all input or output done on the file. The 
basic unit of i/o is the sector of 64 words. Any number of 
sectors may be read or written at one time. 

To open a random file for readings use the call 


unit = open( filenames, "rb" );7 
The rules are the same as’ for the regular OPEN calls except 
that the character ‘b* in the action string indicates that 
the file is to be accessed as random. The action ‘b*® stands 
for “block” - we would have used ‘r‘ for “random”, but it is 
already taken for “read”. 
To open a file for writing or reading and writings use 
unit = open( filenames “wb” ); 
Reading 1s accomplished by 


status = read( units buffers sectors nwds )-, 


"buffer™ ts a pointer to a vector into which the data will 
be reads “sector” indicates at what sector in the file the 


read will starts and “nwds" indicates how many words will be — 
transferred. The first sector number in the file is zero. If 
the status returned 1s non-negative it is acount of the 


number of words transmitteds otherwise it is the negative 
major (bad) status from the i/o, 
Writing 18 accomplished by 


status = write units buffers sectors nwds )e 


The arguments have’ the same meaning as those for READ. The 
GCOS disk 1/0 system always writes a multiple of 64 words. 
If the number of words you transmit is not a multiple of 64, 
the unused fraction will be filled with zeros on writing. 


Z-2- String operations. 

The 8 compiler recognizes the existence of strings on- 
ly in that it handles string constants. All operations on 
strings are handled by function calls. Recall that a string 
is a sequence of characters packed four to aword in a vec~ 
tor and terminated by the ASCII ‘**0O°, 

Functions are available to permit processing characters 
in a string ina "random" manner or character by character. 
We will also mention several useful string utilities. 
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fede]. "Random" string grocessing. 


ch = char strings 1 )-e 
Returns the ith character ina string pointed to by 
"String”. The count always starts at zero. 


ch = [chart strings As char )7 
Replaces the ith character in the string pointed at 


by “string™ with the character "char" and returns as 
Its value the character supplied, 


Where characters are in BCD format (6 characters per 
word)s you should use the function CHARB instead of CHAR and 
LCHARB instead of LCHAR,. The calling sequences are the same, 


but remember that they take and return BCD characterss not 
ASCII. 


f.3-2- Sequential string access. 


By using one of the following callss it is possible to 
"open" a string in such a manner that calls to regular 
sequential i/o routines place characters in or return char- 
acters froma string. This method is faster than using 


CHAR/LCHARs because the implementation uses hardware “tal= | 


lies". The actien “s* stands for “string”. 


unit = open( strings "rs" [Eepos] )- 

Opens a string so that calls to GETCHAR will return 
characters in the string. A call to GETSTRING returns 
all characters up to but not including the next **n' 
or else up to the terminating **0*. When the string 
1s exhausteds the unit is in EOF status. If you want 
to start getting characters at some point other than 
the first character positions use the optional start- 
ing character position “pos”. Any library function 
which obtains characters from an i/o unit will also 
work even if the unit 18 a string. 


unit = open strings "ws" CFeposl] )- 
Opens a string so that calls to PUTCHAR place charac- 
ters in the string. PRINTFse PUTSTRINGs PUTNUM and 
other functions will also send characters to the 
String. The function: of “pos” is the same as 
described above. 


unit = open( strings "as" )- 
locates the terminating ‘**0° of “string” and sets 
things up so you start writing into the string at 
that point. If ¥8 up te you to make sure that the 
vector pointed at by “string” is large enough to hold 
whatever your program puts into it. 
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printt strings formats arais afo2s «6. )? 


Same as PRINTFs except it directs its output toa 
strings instead of an open output unit. 


When you call CLOSE on a unit open for output to a strings a 
terminating '*0" is placed in the string. 


Leded- String utilities. 

String = concat(t st#inge-s se $23" sea-d> 
Concatenates the strings "si" through "sn" together 
and places them in string "string". The output string 
may be used as inputs providing it appears first in 
the list of strings to be concatenated. When called 
with only two argumentss CONCAT efficiently copies 
one string into another. CONCAT returns its first ar- 
gument as its value, 

val = nullstring( string );7 
Returns a non-zero value if the string contains only 
the end-of-string character "*0' and zero otherwise, 

val = equal( stringls stringed )- 


Returns a non-zero value if the two strings supplied 


are identicals and zero otherwise. | 


count = length string )- 


Returns the number of characters in the string point- 


ed at by “string"s not including the terminating 
wt? . 


result = compare( stringl, string2 ) 


pos 


This compares two strings. If they are equals COMPARE 
returns zero. Otherwises it returns a value one 
greater than the position in "“stringi" where they 
differed. The returned value is positive if “stringi” 
1S greater than “stringe™s Of negative if “stringi” 
$3 tess Fhan “strinaec”. 


= any( cs string EFril )- 

If the character "“c" appears anywhere in the string 
"string"s with scanning starting at character posi- 
tion "i" (which defaults to zero if not supplied), 
then the position of the character in the string is 
returned. If the character is not founds then the 
value “-1" jis returned. 
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newpos = getarg( arge strings pos [edelim] )-, 3 
Starting at position “pos” in “string”»s GETARG ob- 
tains the next group of characters ending with a 
blank and places it in the string pointed to by 
"arg. it returns the position in the string where 
the scan stoppeds so that it can be called repeatedly 
to obtain successive “arguments” from the string. If 
“delim” is supplieds it is taken as a pointer to a 
string containing the delimiters which will cause the 
scan to stop, the string must Include a blank if you 
want the scan to stop on a blank, Leading blanks are 


ignored. GETARG is useful for scanning a command 
line. 


There are .a number of other functions which perform 
string operationss including NUMARGs which scans off numbers 
instead of character stringss ADDCHAs which appends a char- 
acter to the end of a strings and READFs which can do for- 
matted input from a string. All of these have explain files. 


2-6. Storage allocation. | 

Library functions are supplied which allow you to 
dynamically obtain or release memory in the free storage 
pool, — 


addr = getvec( n)- 2 
Obtains from free memory a vector of length "n" plus | 
one words and returns a pointer to the vectore Once 


acquired in this manners the block may referenced us- 
ing subscriptings as 1n 


x = getvec( 63 ); 
xC1J3 = al 3], 


risevec( addres n)-s 
Undoes a GETVEC by releasing the "n" plus one words 
pointed to by "addr" back to the free memory area. 


All memory allocation is done by manipulating a free 
Liste The free List initially includes the so-called “core 
hole”. You can return via RLSEVEC any space which 1s not on 
the free liste as -long as the address of the space is 
greater than the load address of RLSEVEC. If you attempt to 
release memory which is already on the free Lists in whole 
or in parts RLSEVEC will immediately abort. : 

GETVEC obtains more storage from the operating system 
as required. In TSSs a subsystem is aborted with the message 
"not enough core to run job” if a request for memory cannot 
be satisfied. In batches GETVEC aborts with a "OK" abort code 
if a request for memory is denied, 

Finallys we will mention three useful routiness each 
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described fully by an explain files which use these calls: 
GETMATRIX will construct and return a pointer to a multidi- 
mensional matrixs ALLOCATE can be used to obtain a dynamic 
array which will automatically disappear when a function re- 
turnss and RELMEM will release any free memory back to the 
operating systems in order to reduce program size, 


feof. Character code conversion. 

Two functions are supplied to let you transliterate 
BCD into ASCII and vice versa. A BCD string consists’ of a 
vector of words containing the characters packed six to a 
words left-adjusted and padded with blanks. There is no e- 
quivalent to the '*0°' in a BCD string. 


ptr = ascbhcd( outputs counts input )- 
Takes "count" characters from the ASCII string "in- 
put", transliterates them to BCD and places them in 
“output”. If a '*0" is encountered before “count” is 
exhausteds blanks are supplied and also used to pad 
the BCD string to a word boundarye “input” and “out- 
put" must be pointers. “output” is returned. 


ptr = bedasc({ outputs Inputs count )- | 
Takes “count” 8CD characters from ‘“input"s thansii= 
terates them to ASCII and places them in. the ASCII 


string "output". Any trailing. blanks are deleted and = 


the end of string delimiter ‘*0°* is placed at the end 
ef the ASCII string. “tapot™ and *“svutput” must be 
pointers. "output”™ is returned. 


7.8. Call FORTRAN. | — 
The function CALLF provides the ability to call FOR- 
TRAN subroutineSs or any routine which uses the GCOS CALL 


conventions. Howevers routines so called must not be called 
recursively. 


intval = callf( 8routines &arglis Barges wee )2 
Converts its arguments to the form of a standard GCOS. 
CALL macro and calls the named “routine”, "routine" 
must be referenced in an EXTRN statement and must be 
passed by address as shown. The arguments must. be 
passed by address also. fhat iss if an argument is 
not a vector pointers you must say "Sarg". Constant 
values must be assigned to a temporary before being 
given to CALLFse since you can't say something like 
"Z2". The walue of a CALLE is the togical or integer 


value returneds if the routine called is a function 
subroutine, 
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floatval = callff(€ @routines Sarglr &argesr wes JF 
Works exactly the same way as CALLFse except that it 
must be used for function subroutines which return a 
floating point result. 


As usualy you are responsible for ensuring the correct 
number and type of arguments are passed. 


£.2- DRLsS and MMEs. 

For those Chopefully rare) occasions when you need to 
perform system calls directlys here are the functions pro- 
vided to let your 8B program execute DRL or MME system calls 
in a reasonable manner: 


drl.edri(number Csargis arg2sr w«seJ) ) 
Allows direct access to the DRL functions. "Number" 
is the DRL number to be executeds and any following 
arguments are the words to follow the DRL. The A and 
Q registers are set to the values of the externals 
DRL.~A and DRL.Q@ respectively. After the DRL has been 
executed» these externals are set to the contents of 
the A and the @. It is possible to use a DRL which 
requires an error exit or a place to go tos since the 


DRL is executed in the stacks using the stack pointer 


of the caller. For example: 


Zb/manif/drls 
auto buffs vecl2J- 
buf = getvec(600)- | | 
open( 9s “qceos3/gcosshiruse”"s "r" )z 
aft.ename{ 9s vec ), 
vecl2) = *.mbrt3"-, 
dricsdrl Crestor ¢» bBut<<18 | T+ buf<<18 t& 1, 
(tra&0777777000000) I Cbuft+512))- 

tras : 

printf( “%24ben", buft+t4+status*4 )- 
rlsevec (buf 2600), 


This code sequences which obtains a batch error mes~ 
Sage by locating it tn the batch error message 
modules uses the value of a label to supply a return 
address to DRL RESTOR. Note thats in this particular 
cases, you could have called the library function 
eRESTR»e replacing the call to AFT.NAME and DRL.DRL 
with.“ restet 9s >. brits «te bute. 
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mmeemme( number [Cvargls arges «ee | Ds | 
Functions in exactly the same manner as DRL.DRLs ex- 
cept that it uses externals called MME.A and MME.Q, 


8.1. Comoiling/cunning. 

7 The B command is the main toot for preparing’ 8 pro- 
grams. If given a source files, it will call the compiler to 
read the source and generate a set of object modules. It may 
call the random tibrary editor RANEDIT to place or replace 
modules in a library. Unless there are fatal compilation er- 
rorss it always calls the TSS loader to prepare a_ load 
module. Only the most common use of the B command is dis- 
cussed here. For full detailss see the TSS explain file "ex- 
plain b command", 


To compile and load a source files, just type 


b srcfile 

where "“srcfile” is the name of a sequential file containing | 
B source statements. If there were no fatal errorss the load 
module is left tn arandom file called ".h"s which is creat- 
ed as temporary if necessary. If you have a quick=-access 
permanent file called ".h", it 18 used instead. This file is 
"grown" automatically by the TSS loader as required. 

You could have forced the 8 cOmmand to initiate execu- 
tion by entering 


b -go source-file 


buts if your program plans to interpret a command Lines it 
is preferable to use the command GOs like 


60 @faql a@Fa?e sess 


which will run the load module in ".h" with the given com- 
mand Line. 


There are a few other options in the 8 command which 
you may find useful. If you find you are allocating too many 
AUTO variablesse so that your program violates the stack lLim- 
it and overwrites your Own coder you can specify a larger 
stack by using the “"Stack=nnn" options as in 


b srceb stack=/700 


Waterloo “56> March 1979 


Fully debugged production programs need not carry the debug 
tables with them when running. Use the "=Nodebug"” option to 
turn off the loading of debug tables. 


b -nodebug src.b 


If you change one routine in a programs you usually 
have to recompile the whole program. It 1s sometimes more 
convenient to store routines in a random library. That ways 
you need only recompile one routine or one group of routines 
to make a change. The 8B command provides)7 an interface with 
the RANEDIT subroutine library editor. To start withs if you 
type 


b sftctib fFanetab=/tib =¢lear 


the routine or routines in src.b will be edited into the li- 
brary “lib"™s which will be created if necessary according to 
the usual 8B file accessing conventions and initialized 
(cleared) by RANEDIT. To add new routines or replace old 
onese you simply enter , 


b srcoi.b ranelib=/lib 


Your program can load from a user Library by specifying the. 


"Library=" options as in 
b src.wb library=/lib 


When the loader is calleds the library specified by the "r=" 
option 1s searched along with any other libraries given us- 
ing the "l=" option. Libraries are always searched in the 
order given on the command line. To delete routines from a 
libraryse it 18 necessary to use the TSS command RANEDIT (see 
the TSS explain file). 

The options to the B command are of the forms 


keyword=string 
“keyword 


In both casess the keyword may be abbreviated using the fol- 
Lowing rule: In the explain files, a keyword is shown with 
upper and lower case letters. A valid abbreviation must in- 
clude those letters which are in upper cases along with any 
other letters in the order in which they appear. For exam- 
ples valid abbreviations of the "Ranelib=filename™ option 
include 


rane=filename 
rlib=filename 
r=filename 
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Various options mayer of courses, be combined onto one 
command line and abbreviateds as in the following examples 


b cmdlib/s/roff h=cmdlib/roff l=b/xlib -n -d 


This command line uses the option "Hstar=filename”"»s which 
allows you to designate the file into which the generated 
load module will be placed. 


8.2. Debugging. 

Rarely will you find that a newly-written 8B program 
works the first time you try to run it. Typicallys it may do 
nothings it may go into an infinite loops or it may abort 
with memory fault or some such hardware-detected error. 

The most useful.tool for debugging programs is BOFF, 
which stands for "B Obscure Feature Finder™. You can use 
BOFF in three modes: to inspect and/or patch the core image 
file prepared by the loaders to monitor the progress of your 
program as it iS runnings or to inspect a TSS dump file, 
called "“abrt", after your program has died. 

In this sections we will look at some of the basic pro- 
cedures to follow when debugging a programs using BOFF. For 
full details on BOFFs, see the explain files. 

Usuallys the first thing that happens is that you try 
to run your program and it abortss leaving an abort file 
containing the dump in the AFT. To look at the dumps type 


boff -abort 


BOFF will display the fault type- the value of the instruc- 
tion counter at the time of the faults ands if debug tables 
are availables the abort location expressed as an offset 
from the toad table name whose address: if closest to and 
less than the abort location. For a batch abort files the 
fault type is always “incorrect primitive”’s howevers, you can 
determine the actual fault by looking at the execution re- 
port. | : 

In BOFFs displayed numbers are shown in octale but when 
snapping memory locations you have the option of changing 
the form of the display. A number which BOFF reads from the 
terminal may only be an integers which is taken as octal if 
it has a leading zeros and decimal otherwise. In other 
wordss every time you type 3n an octal numbers you have to 
St tce 2 £8Pfo tn front of it. 

The first thing you will want to do with an abort dump 
is to try to get a traceback of calls in reverse order, Type 


ae 
For each calle the traceback shows the stack pointer used 


during the call, the function names the argumentss and the 
symbolic address from which it was called. 
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There are a couple of things you should keep in mind 
when looking at a traceback. You may see function names in 
the upper part which are not part of your programs this me- 
ans your program died ina library function. The arguments 
displayed for a library routine may not look Like what you 
expect; this may be due to your program passing bad argu- 
mentss but it is also quite common for a library routine to 
modify an argument or use it for a different purpose. 

If you are luckys your problem will be a bad argument 
and a solution will suggest itself. More likelys» you will 
want to inspect the state of the various variables in the 
program. You can look at any external value at any times but 
you can only look at the arguments and AUTO variables of the 
current functions which is initially the topmost function in 
the traceback. BOFF provides two commands which Let you move 
the current function context either up or down in the trace- 
back list. 

For examples suppose you have the following traceback: 


00221 open (0150) rets to 003306 (readf +0410) 


00151 readf (01162,0777777777766) rets to 001160 (funct010) 


00147 func (0777777777766) rets to 001140 (main +06) 
00145 main (056150000132) fFets to OOTS2I Ccscasca #017175) 


The program has died in the library routine OPENs which was 
called from another Library functions READF. In facts the 
cause of this particular abort was a bad argument to READF, 
The initial context is that of OPEN» whichs being a library 
routines probably has no debug tables. To Switch the context 
to MAINs tell BOFF to move down the stack three functions by 
giving the command 


$id 


From theres to get to FUNC’s contexts you would tell BOFF to 
move up one function by typing 


tty 


As you can sees, context positioning on the stack is 
specified by giving the number to moves followed by a colons 
followed by the directions which is either ‘u’® or ‘'d'*, 

Suppose you tell BOFF to move up or down too far ? BOFF 
will leave you in areasonable place. To find out wheres 
type 


2Vva 
which will show the name of the function whose context 15 
currents ands if there is a debug table for the function, 
the names and values of the argumentss automatic variables, 


and Labels of the function. Remember that "va" means "View 
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To snap memory in BOFFs use a command formed as fol- 
lows: 


CaddrjJCenwdsiC\mode] 


where the square brackets indicate an option. 

The “addr" must be an lLvalues which means that it must 
be in either the form "name" or the form “*xnnn", where "nnn" 
1s a number. If you do not supply an "addr", BOFF uses the 
last address displayed plus one. 

The “"nwds"™ is usually a number. If not givens, it de- 
faults to one, | 


The “mode™ is a _ possibly null string of characters, 
which can include: 


- address format 

- BCD constant 

- ASCII character constant 

decimal 

- floating point 

- interpret as machine instruction 
= octat 

- display B string 


nO -—- »~O 2 CO ® 
} 


l¥ the string i$. nutis the wmode 1§ octai,. 1t.*\* 38 tee. 
availables, you can use ‘*"* jnstead. lft. “mode” i$ nee 
presents the last mode is used. The initial mode is octal. 

To snap a variable called "x"s you might type 


To snap it in octalse BCD» and ASCII» you would say 
x\obc 


To snap the contents of the ten word vector "y(f10]", 
you would enter 


kyl 


To snap the vector in octal and address formats you would 
type 


xyelit\oa 


To snap the first 20 words of the function MAIN»s you 
would Say 


mainse20\1 


The lLvalue of the expression “main” is the address’ of the 
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routine "main", which is where BOFF starts snapping. To snap 
the next 20 wordss enter one of the following two alterna- 
tivess 


*C&maint+20) 220 
220 


Since no "mode" is givens the Last mode is used. 
To snap 20 wordss starting from location 110 (octal), 
you would type 


*0110,20 


When you go onto read the full BSOFF documentations you 
will find that you can construct arbitrary expressions com- 
posed of namess integer numbers» and a subset of the B 
language operators. 

At this points we have covered the basic information 
you need to know to use BOFF an abort file. It is more like- 
ly that you will want to use BOFF on your ‘program as it is 
running. In this modes not only can you use everything men- 
tioned so fare but you can also set breakpoints and execute 
function calls from BOFF, 

To run your program with BOFFs give the command 


bofftch arg arg see 


BOFF will set a breakpoint at MAINs so you will get control 
in BOFF just before MAIN 1s executed. 

When you get controls the current context for the “tva" 
command will be MAIN» the function at which the breakpoint 


is placed. The commands for moving up or down the stacks for 


snapping memorys and for printing a traceback will otherwise 
work as described above, | . 

BOFF makes it very convenient to put a breakpoint on a 
function. If your program consists of a number of small 
functionss rather than one monolithic MAIN functions, it will 
probably be easier to debug. 

To put a breakpoint ona functions use the "“sbf™" com- 
mand as follows: 


name:bf 


where "name”™ is the name of the function. To delete such a 
breakpoints use the command: 


Nname:zbd 
You may also want to know about what value a function 
returns. You can set a function return breakpoints but only 
at the function entry breakpoint for that functions by typ- 
ing the command 
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Finallys you can calls from BOFFs any function defined in 
the programs with arguments. For instances, you might say 


pr inti Ooze ferme “gectd'*s cD 


This example shows that not only can BOFF read numbers and 
variable namess but it can also read B string and character 
constants. BOFF will always print out the value returned by 
the called function. If the callee does not deliberately re- 
turn a values the displayed value can be disregarded. 


8.3. Compiler/loader interface. 

| When processing a source programs the compiler gen- 
erates not one but a set of object decks and places them on- 
to a temporary file called "b*" = the input file for the 
loader. This file is also used as input to the random li- 
brary editor RANEDITs if it is called. 

The compiler always generates an object deck containing 
the B stack areas which is either $00 words or the size 
specified in the "Stack=nnn" options This object deck also 
contains the externals defined before the first function de- 
finitions, if any. 

A separate object deck 1s generated for each function, 
The deck includes a SYMDEF for the function and a SYMREF for 
each name mentioned in an EXTRN statement or used in a func- 
tion call. 

An object deck is also generated for each group of 
externals between function bodies and one for the group of 
externals after the Last function bodys if any. The deck in= 
cludes a SYMDEF for each defined external and a SYMREF for 
any external name referenced in an initializer list. 


8.4. Using tabs for readability. | 
When you type in aB programs you will probably want 

to leave indentations in order to make clear the order of 

nesting of your source statements. , 

Spaces are the logical thing to uses but they are tedi-~ 
ous to type and it is difficult to be consistent. At Water- 
loos we usually suggest you use an ASCII tab character as 
one unit of indentation. This has the advantage thats when 
you use TLIST to get a listing of the sources the TLIST com- 
mand automatically expands tabs into the right number. of 
blankss so your program comes out indented the way you want. 
Alsos you can use the "OTD" directive inside the QED text 
editor so that its toos expands tabs when displaying a line. 

Tt is not oossible to use a “tab character” which 1s 
not an ASCII tab. 
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8.3- Some pitfalls. 
If you have a floating point values it 18 not a good 
idea to say 


1f¢ fleaetvatl 3. Vea 


because the code generated checks to see if "floatval” 15 
lLogicatly non-zeros rather than to see if it 1s equal to a 
floatina=-point zero. Since a floating point zero may not in 
fact be a word containing all zero bits (since the exponent 
may be non-zero and is part of the word) it 1s better to try 


If floatvat #12 GLO 2. ue. 


In generals floating point is tricky to use in Bs since 
there can be no type checking. You must constantly watch out 
for erroneous constructs such as using “-3.0" instead of "#- 
Sas 


Also» here is a common pitfall in the use of string con- 
stants. If you say ‘ 

auto x{20]; 

x = "ga string”: 


The cell x is changed to point to the storage occupied by 
the string and you lose the ability to address the 21 words 
originally reserved for the vector. What you really want to 
Say 1s 


auto Xx, 
x = "a string", 


Alternativelys if you had wanted to initialize the vector 
with the strings you should have used the library function 
CONCAT to copy in the string: 


auto x{20]- 
eoncat( xz “a string")? 


or else you could have defined "x" as an initialized exter- 
nal. : 


Finallys something should be said about the size of a vector 
and the length of a string. : 

When you declare a vector of size "n"s you know that it 
witl actually occupy "n + 1" wordss because the vector is 
indexed starting at zero. Every library routine to which you 
must pass the size of a vector observes exactly the same 
convention, 
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In practices if one needs a vector of size "n", then one 
declares it to be of size "n"» and then ignores the zeroth 
or the nth word. Thus a FOR loop indexing through the vector 
might run in either of two ways: 


for (¢ 7 = 0; j < ne ++} ) see 
Tor(€ . 4.°R 42..49 €2 ops 3. wx 


Strings also can be indexed intos using library func- 
tionss using a zero origins but at first it might appear to 
you that a string with "n" characters in it has length "n", 
rather than "“n + 1". For examples the string "abcdef" has 
six characters and its length is six. But recall thats by 
definitions a string is terminated by a ‘'*0" character, 
which you do not see. If you include the trailing ‘**0* in 
the counts then a string of length "n" actually contains "n 
+ 1" characters, 

All library functions which require the length of a 
string need the number of charactersse not including the 
"*xO'. The Library function LENGTH returns just that number. 
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APPENDIX A 
Escape sequences 


There are two sets of escape sequencess one for use in- 
side string or character constantss andthe other’ for use 
outside. 


Ts Escape sequences are used in character constants and 
strings to obtain characters which for one reason or another 
are hard to represent directly. Here are the escapes: 


aQ . end of string (ASCII NUL = QO0Q0) 
xe end of string (ASCII NUL = OOO) 
* ( { - left curly brace 

* ) } - right curly brace 

aK {[ - left square bracket 

* > J - right square bracket 

*t tab 

xk * * 

* ? 8 

x * e 

*n newline 

xr carriage return (no line feed) 
xf ASCII formfeed 

* b backspace 

xy vertical tab 

* Xx rubout Coctal 177) 

tHnnn nnn 3s 173 character octal number 


2. The following are escapes used outside character and 


string constants on terminals (such as the 2741) which do 
not have on their keyboards some of the characters used by 


B. If you use QEDs it 4§ nicer to use the G&D escapes for 
these characterss so that when you shift to an ASCII termi= 
nal you can see the characters the way they ought to appear. 


$ ( { - left curly brace 

$) } - right curly brace 

$< {[ - left square bracket 

$> J - right square bracket 

$+ | “-or<-bar 

_* " ~ uptarrow (for cent~sign) 
$a a - at-sign 

$ ° “= grave accent 
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APPENDIX 8B 
Binding strength of operators 


Operators are listed from highest to lowest binding. 
Strengths there is no order within groups. Operators of 
equal strength bind teft to fight or right to left as indi=. 
cated. : 


pee name const primarylexpr] primary(arglist) (expr) CLRI 
i t+ -— 28 & - $ R= RAN Conary) ERED 

f s> << EL) 

= ae CLR] 

He See : CLRI 

| | [LR] 

Paes x | % He HI Chinary) ELS 3 

ne + = He ft CLR]. 

f == is > < <= 3s #== Bie > Hc H<e Hes Hie gos 
, 8&8 

23 a4 

1294 2» CRLI 

ff = += -= etc. (Call assignment operators) [RL] 
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APPENDIX € 
B compiler error message 


This is a list of diagnostics known to be generated by 
the B compiler. There may be others. 

In each descriptions "nn" means a line numbers while 
"“name™ is some identifier name. The name of the source file 
1s usually also given. 

Any message not preceded by "warning: "™ is a fatal er- 
ror. If there is afatal errors, neither the loader nor the 
random library editor will be called. 


Diagnostics: 

Syntax error at Line nn Cin file <name>] 
This 18 the most common diagnostic and it could mean 
almost any kind of error. Most oftens it means a sem- 
1colon 18 missing or the number of open curly braces 
"{" does not match the number of close curly braces 
"+", in which case the Line number will be the number 
of the last line in the last file being processed 
plus one, This may be due to neglecting to end a 
string constants character constant or comment. You 
also get this message if you use a keyword in an 
inappropriate contexts such as an AUTO statements, if 
you neglect to define a manifests or if you attempt 
to redefine a manifest. 

<identifier> undefined in function <name> 
An identifier in the named function has not been 
referenced by an EXTRN or AUTO statement and has not 
been used as a tabel. The line number given is the 
last line of the function being compiled. 

warnings /* inside comment .ee 
This 1s a warning onlys but there will probably be a 
syntax error later ons since comments may not. be 
nested. After reading a "/*", the compiler skips all. 
text until a “**/" is encountered: if there is a com- 
ment inside a comments then the compiler will attempt 
to compile the remainder of the outside comment. 

end of file in comment 
This usually indicates that you forgot to end a com- 
ment with the terminating ‘*/', 

warning: newline in constant not preceded by * 
The most probable cause is that you forgot to ter- 
minate a string or character constant with the ap- 
propriate delimiter. If this is the cases, you will 
surely get a syntax error later. If you want a "real”™ 
newline inside the constants but no warnings use the 
escape sequence ‘'*n', If the constant 1s a string 
constant which is too long to fit on one Lines pre- 
cede the newline with a ‘*'s the newline will be dis- 
carded. When the warning is issueds the newline is 
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kept. 
invalid octal constant 
An integer beginning with the digit zeros, which is 
thus assumed to be an octal constants contains a 
character other than the digits zero through seven. 
character constant too long 
A character constant may not contain more’ than four 


characterss although each character may be a _ two 


character escape sequence. 
bcd constant too long 
A BCD constant contains more than six characters. 
exponent too large in constant 
The exponent of a floating point constant is too 
large or too small to represent in the hardware. 
attempt zero division 
In evaluating the constant part of an expressions the 
right operand of a division or remainder operator was 
found to be the constant zero. 
invalid & prefix 
The "&" operator has been used in an invalid context, 
such as “&x = y"™, 
warnings found ++r-value 
warning: found --r-value 
You get this if you say something like "++x++", 
invalid $ escape sequence 
An escape sequence beginning with ‘S$* is not known to 
the compiler. 


invalid unary operator 


The compiler discovered you trying to use a binary 
operator ina unary manner. 

invalid = 

invalid *= 

invalid >>= 


The expression on the left hand side of an assignment _ 


operator does not have an tvalue. 

invalid ++ 

invalid -=- : 
The expression operated upon by the +4" of tee! 
operator does not have an lvalue. 

invalid label : 
A name used as alabel has previously been declared 
as EXTRN or AUTO in the current function. 

invalid break : | 
The compiler found a BREAK statement which was not 
inside a FOR» WHILE» DO-WHILE-, REPEAT or SWITCH 
statement. 

invalid next 
The compiler found a NEXT statement which was not in- 
side a FOR» WHILE» DO-WHILE or REPEAT statement. 

invalid constant expression 
Will happen if you try to use a string constant ina 
constant expression. 
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Invalid operator 
This 18 one of those “cannot happen" messages. If it 
does happens please submit an error report. 

auto array too large 
You attempted to declare an auto vector with a dimen- 
$10nN greater than 1000 words. It is better to use an 
external vector or else GETVEC the spaces since AUTO 
variables are allocated on the stack and stack space 
1s Limited. 

extrn array too large 
This will happen if you declare an external vector 
ttke “xC3.077".. : 

invalid case 
A CASE label is not inside a SWITCH statement, 

invalid default 
A DEFAULT Label 31s not inside a SWITCH statement. 

default already supplied 
More than one DEFAULT Label in a SWITCH statement. 

invalid case operator 
The only bound operators permitted ina CASE are <, 
>p OS, and <=, 

%Afilename tqnored- too many open files 
This usually happens when you include a_ file which 
includes itself. 

bad input characters <ddd> (Coctal) 
A character encountered in the input stream outside 
of a string or character constant has no meaning for 
the comnoiler. This might be a backspace or some con- 
trol character typed in by mistake. Since it may be 
non~printings the value of the offending character is. 
displayed in octal. 

rewrite this expression 
A subscripting expression is too involved for the 
code generator to handle. Try breaking up the expres- 
s$i0n into more than one statement. 

manifest nesting too deep : 
This will occur when you have manifest constants 
whose evaluation. involves other manifest constants. 
This will occur if you have a series of manifest de- 
finitionss each of which is defined in terms of the 
previous manifest. This iS Ok in GMAPs but not in B. 

warning: program size > 32k 
One of the object decks generated will require more 
than 32K words to load. You may get this warning if 
you declare several very large external vectors. How- 
evers it might also mean the loader will be aborted 
by TSS due to “not enough core to run job”. 

expression too complex 

no tree space 

no stack space 
An expression is too complex for the compiler to 
evaluate. Try simplifying it by breaking it up into 
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two or more expressions. 

The constant <ddd> occurs in two case labels 
The same constant appears in more than one CASE label 
In a SWITCH statement. The value of the offending 
constant 1s printed in decimal, 

the upper range <ddd> overlaps the lower range <ddd> 
The compiler has detected overlapping bounds inside a 
SWITCH statement. The values of ‘the bounds” are 
displayed in decimal. 

The constant <ddd> is in the range <ddd>:3:<ddd> 
The compiler has detected a CASE constant which is in 
the range of a range case or relational cases ina 
SWITCH statement. The numbers are given in decimal. 
If something conflicts with a relational cases then 
the bounds generated for the relation are shown, For 
example, the bounds for "case >. O23": wpwoutd Be 
"Pe e356559 7358567" | 

Initializers nested too deeply 
An external declaration has initializers in braces 
nested to a depth greater than seven. 

external redefined 

auto variable redefined 

label redefined 

auto array name redefined ? 
The compiler has detected an attempt to redefine a 
symbol which has already been defined to the current 
function body. 


no space for symdef 


There are too many external definitionss try dividing 
them into two groups by either compiling them 


seperately or placing a function in between. This er- 


ror is almost never encountered, 

no space for symref 
There are too many external references in a function 
definition; try simplification. This error is almost 
never encountered, 

warnings #<text> iqnored = 
A line beginning with a *#*»s which is taken’ to be a 
compiler directives, does not contain a recognizable 
directive. The line is ignored, 


TSS loader warning messages: 

<w> name undefined Be 
This is a tloader messages which indicates that an 
external variable referenced by one of your func- 
tionss or a library functions remains undefined after 
all libraries have been searched. If your’ program 

references the named external it will abort with a 

MME fault tn. TSS) Ge with a USER*S EY MME GEGORT in 
batch. : 

<w> name loaded previously 
The loader has discovered a function or external with 
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a) Shc the same name as one already loaded. The most 
i probable reason is that you have two or more dif- 
| ferent names whichs when truncated to six characters. 
6| end up being the same. The loader ignores all but the 
i first. Make sure alt your externals and function 
| names are unique in their first six characters. 
q 
aS a 
| \ aaa - SUE ac tas < 
es . 
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~ABBRV 
sBUFFE , 
eBSET ° 
oFEDIT 
GROW ., 
~GSNMB 

e IDENT 

el OSTA 
eLEAVE 
ePROFICE 
esREAD 
eREMOV 
-RESTR 
STARS... 
e TRACE 
sWRAP. 
eWRITE 
ABORT . 
AGS s «. 
ACCUSES IES 
ACCLIB 
ADDCHAR 
ADDVEC 
AFT .NAME 
ALLOCATE 
ANY 4 5 
APPLY 4 
ARS ‘« -» 
ASCBCD 
ATTACH 
BACKSPACE 
BACK. DOOR 
BCDASC 
BCDADD 
BCDSUB 
BINBCD 
C.READ 
C.WRITE 
CALLE og 
CALLFF 
CATSCAF 
CHAR ” 
CHARB ., 
CHARP 4 
CHCKSM 
CLOSE 5 
CMPC ° 
CMPLOG 


Waterloo 


call 


FORT 


2 2 2 _* e 2. f= s 2 se 2 = 


APPENDIX D 
Index of B library routines 


check for valid abbreviations 
define a debugger breakpoint 

parse string into arguments 
edit a filename for printing 
grow a file 
ce. eo eee os ew le. Gener ere. 3. Shuts 
- write an ident image for a backdoor file 
find 10 status for a unit 
owe 6 « © ow es [heave file actessed on close 
generate profile of a B program 

reference or change the current read unit 
‘2. a oe force deaccess of file on close 
‘ Load an element from an hstar or system 
set tabs for the current output unit 
er Ge oe ee ee ee ee set trace output unit 
o 2 «© «© user specified termination actions 
reference or change the current write unit 


rt jobs producing dump and returning status 
° 2 «© « «© « « absolute value of an integer 
6 ee eae SR Se a ee access file 
cs Soe Soe access the system libraries 


adds a character to the end of a 8B string 
*. 2 replace a vector by a news larger one 
—<— +.» » ~¢ Boe be return aftname/filecode 
simple garbage collecting storage allocator 
- check if a character appears in a string 
arbitrary function with arbitrary arguments 
: eee ee eee Ere Ff iek & aie tt 
e convert an ASCII string to a BCD vector 
“eee oe a attach file to task file list 
°« « © back up output unit by one character 
submit a file to the sysout backdoor queue 
convert characters from BCD to ASCII 
0 ee eee re add two bcd numbers 
o 8 & 6.8 8 2 & = —eeetrect two BCS numbers 
convert a binary number to bed 
force unit to be read unit. 
force unit to be write unit 
ss * call FORTRAN program from 8B routine 
RAN function returning floating-point value 
ae te turn pathname tnto Filsys format 
extract ASCII character from string 
ee ee extract BCD character from string 
« S$@t up a character pointer into a string 
S compute a checksum 
close currently open unit 
‘0 e+ ee eee 8 ES BITING Compare 
compare two values logically 
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CMPVEC Sor ee compare one 8B vector to another 
COLUMN ee ae ae oe a ee ee find current output column 
CGY ORt ° ok se. Bo eS ae eee 6 compare two 8B strings 
CONCAT Tae oe oe ee ee ee concatenate a series of strings 
COPY « s «© «© «8» «© C€Opy contents of one vector into another 
COPYCH ca eS oe ee ‘character copy and substring function 
DATE ee ee EE eS ae a eee return current date in ASCII 
DATEJUL : conversion from normal date form to Julian form 


DATESI ° convert date in ASCII string to a standard form 
DATEV .. return current date & time as vector of integers 
DAYMON oo pe ee eee convert date to dd/mmm/yy format 
OiV 4 integer divide with uniform direction of truncation 
DRL.DRLEL 2 « «© «© «© Oxecute a given TSS Derail (system call) 
eins SS. «6. se -* eae w Se Raw Se get status of batch job 
DTOA 6 ae Le Oa eS ee decimal Cintegers) to ASCII 


DUMP — oe 2a oe Ce ae eS Ce Oe Ge oe ee ee ee ee ee ee ee dump vector 
DUMPA 2 kk kk ae ew ee a ee dump an array 
EBCASC i ee we Se convert string from EBCDIC to ASCII 
EOF 234 test input end of files or write output end of file 


EQUAL ie eee ae ee eo ee ee ae compare two-strings for equality 
ERROR Or ae ee en ae eae a type an error messages then exit 
EXLT ne. ea: « * 816s ae ew Se end job and return status 
EXTERNAUS So 6 6 we we useful externals in the 8 Library 
FILDES Se woe we ee ew a eee cet file dese rinter word 
FLUSH fae 8 ck ee ee ee we ae Feces 176 toe end ef. tine 
PPINPOt- yw 0 ee a we ows ASE C6 14 Geti ng. ootat b> iners 


FRO gow es « & ose eo &. a ee ee eS floating point output 
FSFILE aS Sy ee Space input file forward one file 
GETARG oe wo extract (command) arguments from a string 
GETBIN : read vector of binary data from sequential file 


GETCHAR/GETC ee ee a ee we ee read 2 character 
GETDATE «<6 « «© « « turn ASCII date into the form nafdd7yvy 
GETLINE eG Car a ee er oe ee ee read a line from an input unit 


GETMA TREES 6 yg oe we ee dynamically allocate a matrix 
GETMEDIA ee ee ee find media code of file 
GETNUMG 5 fas read a number from the current input unit 
GETREC »« «© get next logical records with rcws from a file 
GETRCP cs 6 0.6 * 6 8 0 © se oe ees GRE fet ore Betnter 
GETSTR co + 6 6 6 6 woe «. POAS Se Set iae Tree an. inout unset 
GETTAPE 2 6 «014 62 @ «© ¢) so #50 eee TOR 2 eee fee SCs 
GETUMC es « be «6 S eee ee ee Ut userid of Surrent user 
GETVEC oe ee ee dynamically allocate a vector 
GNUMBER. 4 26 te ee we ee aw ee tract number frome string 
GOTOSS . « « » « « execute a TSS commands never to return 


GTB convert gray code to binary (execute a gtb instruction) 
HIST ne ee ee ree ee ts ee The B histogram package 
HISTROES TROY i we ow eS Free space used by a histogram 


HISTING Ge ge eS Allocate and initialize a histogram 
HISTOGRAM  . . 2 6 « 6 ew ee el UA & BIE Eo a hi stogres 
HIST 8 4S ee eee ee Print accumulated histogram 
Ero) en ee ee ie oe ee oS find ID of executing DRUN 
INCRUN . ce pe e ea oe Getetatace 1f: a weet fs in 8 Fes 
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INTREQUEST eee handle interrupt (break) requests 
oS ee oe ee ee ee a tell whether running batch or TSS 
IOERRORS ‘ shange default handling of file access errors 
PPLPER Le ~-6. 6 «« conversion from Julian to normal date form 


CCAR 6 ae 6a a ee replace ASCII character in string 
LCHARB Sew we ae eee replace BCD character in string 
LENGTH re return the length of a string 
LINUMB os « « « « return the -eurrent tine number of a fite 
POWERUASE. . «.« turn alphabetics in a string to lower case 
CES eae ee stuff the byte addressed by a charp pointer 
MAIN eS ee Be eee we ae OEE to your program from 6 setup 
MAX Be ee a we a es maximum value of list of integers 
MIN fs ee ee ee minimum of a List of integers 


uid) ee ee ee ee execute a given batch MME (Csystem call) 
MOVELR e e« move characters left to right using an EIS MLR 
MOVERL °e »« move characters right to left using an EIS MRL 
NARGS . « « « « « return number of arguments to a function 


NOBRKS oe ee count number of times break key was hit 
NULLSTRING SS check for null string 
NUMARG . © extract numeric argument from character string 
OPEN es ae ee oe ee ee ee oe open a file or string for i/o 
OVERFLOW ‘2 ae ee oe ee test and reset overflow indicator 
PASUST oo ewe Be a ew ee SRA CUTE 42. FSS ORL Pass 
PEEK oe ee ee ae copy memory into your address space 


PRMRATOCH og ee ee a eA perform simple pattern match 
PRIN - joy o.oo 6s See oS we es do a PRINTF into a string 
PRINTF has te oe ae ee SS ee ee ee ee formatted print 
PROMPT ie oe ee oe oe oe eS prompt for input at terminal 
PUTASC er ee ee ee er ee dumo bytes in ASCII 
PUTBCD oe ee ew ee output the contents of a BCD string 


PUTBIN write vector of binary data to sequential file. 
PUTCHAR/PUTC a a ae oe a oe oe ee ee oe ee ee ee ee ae Fe ee cs 
PUTIIRH. «oy % +. «-@. £8. 62d * 85H output a decimal number 
PUTOCT a a ae ae ee oe SS oe eee es ee ae ee Se 
PUTREC « 2 Output unprocessed record to a sequential file 
PUTSTR eae ea write a string to current output unit 
QSORT ffs 6k nw eae ee a a cc BOE 
RAN.RD ae ae ae ee es Ce ee ae ee ee ee oe do disc i/o 
RAND. ex . © « © © e el hlcelh U6QONC Fate pseudo-random numbers 


RDe»LNK/WR., L NK Sour we 22 oS oe Low level sequential disk I/0 
RDGRAN/SWRIRAN 226k ee ee Low level random disk I/0 
READ/WRITE ee a ee el ee eR Be UNIT er tented Sirnary 376 
READE “5. .« « 6 « ss tw se FO MBtted character stream input 
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RELMEM  . 2. « « e release unused memory from the core hole 
REM = Ss 45 eee ee 6S eC Ee. ae ee EERE SOE: OK SCE Te 
ROMO: <. 6 <4.» Siig we 6 remove file from AFT given pathname 


REREAD Soa a eG back up input to picid naiabhed, of line 


a RETEIL ng i a Ll Trenove a fit 
4 REWIND  . sae s+ + + eMir 
RLSEVEC . ae . 


ROTATE im 
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RSCR e 6 6 eo ee we 6 ew le wl hw OAR uSysten controlter elock 
[7 RSTPSW a Pe oe ee ee ee ee ee er ee turn off: switch werd Sits 
zy SBAR A ee Ee ee te er ee ee oe find size of allocated memory 
SCAF « © « »« convert ASCII pathname to BCD catfile stack 
i SCAN Coa ee BS extract delimited substring of a string 


DC ge i a ae a ew ew ee scan characters under mask 
SETMEDIA oboe ee we ew ee Bienes media code of Sutout fite 
SETPSW ‘or oe ae ae oe ae ee set switch word by bitwise OR 
SUCRE OOR! «we kh 6.6 6. eee r ss. 6) Piece. eo Bet Soret 
SIDATE s.2 0 « « s  CoOnvert standatd date to ASCIT string 
SLEEP 6 6 6 6 6 we ee ew wait for specified interval 
SMC.HASH °o e e« -compute smc hash bucket for a given userid 
STAR i ee ee get the byte addressed by a charp pointer 
STRING co 4 ee Ree! VE e Se ew ew STP IG: 176 Seer 
STRIP aoe. eee cause line numbers to be stripped on input 
SWAPDESCR 2.6 «= « & S 0-+- 0-8: Change progran deserioters 
SYSTEM Soe eS ee ee a ee execute a TSS command 
T2761 6 ee ek ee a ee check if terminal is a 2741 
TABSET eos specify tab stops for the current output unit 
TAY 6 Me 0-8 es we ae ele eo. CPRRES: CHCty te Bo striae 
TALLYB ew « e ] ew ec es «., CROAT Felis ta ASE. Steias 
TAPE eR Swe ee Oe & SEP ESE: 6 See tape 1/0 in B 
TASK cS ee se BOW submit a task job via Derail TASK 
TICK oe ew we we ee return cpu time for current user 


i TIME <2 8 get time in pulsess or convert it to a string 
TROTOD translate to any 9 bit character code from any other 
TRACE soc) es Oe ee eee as B function call-return tracer 

TRIM ‘oe as te ee ee trim trailing blanks off a string 

i TRTEST translate and test characters (fast character scan) 
s TTYN eS ee a determine if 1/0 is to terminal 
UNGETC ee place character in input stream 

i UPPERCASE .« « « turn alphabetics in a string to upper case 

| VECTOR ee create a B vector and initialize contents 
WOLENG (eee «6 eee eee «| OR Ord btesaete ih Gres 

XLATE 2 ooo Lek translate one character code to another 

[| ZERO see 6 ee 8 8 initialise a B vector to some value 


j 
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